Commerce Layer · Capability

Commerce Layer Core API — Promotions

Promotions, gift cards, coupons, and all promotion subtypes: fixed-amount, percentage-discount, free-gift, free-shipping, buy-x-pay-y, fixed-price, flex, external, custom.

Commerce Layer Core API — Promotions is a Naftiko capability published by Commerce Layer, one of 16 capabilities the APIs.io network indexes for this provider. It bundles 15 operations across the GET and POST methods.

The capability includes 8 read-only operations and 7 state-changing operations. Lead operation: List All Promotions. Can be deployed as a REST endpoint, MCP tool, or Agent Skill via Naftiko.

Tagged areas include Commerce Layer.

Run with Naftiko Commerce Layer

What You Can Do

GET
Listpromotions —
/api/promotions
GET
Listpercentagepromotions —
/api/percentage_discount_promotions
POST
Createpercentagepromotion —
/api/percentage_discount_promotions
GET
Listfixedamountpromotions —
/api/fixed_amount_promotions
POST
Createfixedamountpromotion —
/api/fixed_amount_promotions
GET
Listfreeshippingpromotions —
/api/free_shipping_promotions
POST
Createfreeshippingpromotion —
/api/free_shipping_promotions
GET
Listfreegiftpromotions —
/api/free_gift_promotions
POST
Createfreegiftpromotion —
/api/free_gift_promotions
GET
Listbuyxpayypromotions —
/api/buy_x_pay_y_promotions
POST
Createbuyxpayypromotion —
/api/buy_x_pay_y_promotions
GET
Listcoupons —
/api/coupons
POST
Createcoupon —
/api/coupons
GET
Listgiftcards —
/api/gift_cards
POST
Creategiftcard —
/api/gift_cards

MCP Tools

commerce-layer-listpromotions

List All Promotions

read-only idempotent
commerce-layer-listpercentagepromotions

List All Percentage Discount Promotions

read-only idempotent
commerce-layer-createpercentagepromotion

Create A Percentage Discount Promotion

commerce-layer-listfixedamountpromotions

List All Fixed Amount Promotions

read-only idempotent
commerce-layer-createfixedamountpromotion

Create A Fixed Amount Promotion

commerce-layer-listfreeshippingpromotions

List All Free Shipping Promotions

read-only idempotent
commerce-layer-createfreeshippingpromotion

Create A Free Shipping Promotion

commerce-layer-listfreegiftpromotions

List All Free Gift Promotions

read-only idempotent
commerce-layer-createfreegiftpromotion

Create A Free Gift Promotion

commerce-layer-listbuyxpayypromotions

List All Buy X Pay Y Promotions

read-only idempotent
commerce-layer-createbuyxpayypromotion

Create A Buy X Pay Y Promotion

commerce-layer-listcoupons

List All Coupons

read-only idempotent
commerce-layer-createcoupon

Create A Coupon

commerce-layer-listgiftcards

List All Gift Cards

read-only idempotent
commerce-layer-creategiftcard

Create A Gift Card

Capability Spec

core-promotions.yaml Raw ↑ 
naftiko: 1.0.0-alpha2
info:
  label: Commerce Layer Core API — Promotions
  description: 'Promotions, gift cards, coupons, and all promotion subtypes: fixed-amount, percentage-discount, free-gift, free-shipping, buy-x-pay-y, fixed-price, flex, external, custom.'
  tags:
  - Commerce Layer
  created: '2026-05-25'
  modified: '2026-05-25'
binds:
- namespace: env
  keys:
    COMMERCE_LAYER_ACCESS_TOKEN: COMMERCE_LAYER_ACCESS_TOKEN
    COMMERCE_LAYER_ORG_SLUG: COMMERCE_LAYER_ORG_SLUG
capability:
  consumes:
  - type: http
    namespace: core-promotions
    baseUri: https://{{env.COMMERCE_LAYER_ORG_SLUG}}.commercelayer.io/api
    description: Commerce Layer Core API — Promotions business surface.
    resources:
    - name: promotions
      path: /promotions
      operations:
      - name: listpromotions
        method: GET
        description: List All Promotions
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: percentage_discount_promotions
      path: /percentage_discount_promotions
      operations:
      - name: listpercentagepromotions
        method: GET
        description: List All Percentage Discount Promotions
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: createpercentagepromotion
        method: POST
        description: Create A Percentage Discount Promotion
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          required: true
    - name: fixed_amount_promotions
      path: /fixed_amount_promotions
      operations:
      - name: listfixedamountpromotions
        method: GET
        description: List All Fixed Amount Promotions
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: createfixedamountpromotion
        method: POST
        description: Create A Fixed Amount Promotion
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          required: true
    - name: free_shipping_promotions
      path: /free_shipping_promotions
      operations:
      - name: listfreeshippingpromotions
        method: GET
        description: List All Free Shipping Promotions
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: createfreeshippingpromotion
        method: POST
        description: Create A Free Shipping Promotion
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          required: true
    - name: free_gift_promotions
      path: /free_gift_promotions
      operations:
      - name: listfreegiftpromotions
        method: GET
        description: List All Free Gift Promotions
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: createfreegiftpromotion
        method: POST
        description: Create A Free Gift Promotion
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          required: true
    - name: buy_x_pay_y_promotions
      path: /buy_x_pay_y_promotions
      operations:
      - name: listbuyxpayypromotions
        method: GET
        description: List All Buy X Pay Y Promotions
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: createbuyxpayypromotion
        method: POST
        description: Create A Buy X Pay Y Promotion
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          required: true
    - name: coupons
      path: /coupons
      operations:
      - name: listcoupons
        method: GET
        description: List All Coupons
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: createcoupon
        method: POST
        description: Create A Coupon
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          required: true
    - name: gift_cards
      path: /gift_cards
      operations:
      - name: listgiftcards
        method: GET
        description: List All Gift Cards
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: creategiftcard
        method: POST
        description: Create A Gift Card
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          required: true
    authentication:
      type: oauth2
      flow: client_credentials
      tokenUrl: https://auth.commercelayer.io/oauth/token
      value: 'Bearer {{env.COMMERCE_LAYER_ACCESS_TOKEN}}'
      placement: header
      key: Authorization
  exposes:
  - type: rest
    namespace: core-promotions-rest
    port: 8080
    description: REST adapter for Commerce Layer Core API — Promotions.
    resources:
    - path: /api/promotions
      name: promotions
      operations:
      - method: GET
        name: listpromotions
        call: core-promotions.listpromotions
        outputParameters:
        - type: object
          mapping: $.
    - path: /api/percentage_discount_promotions
      name: percentage-discount-promotions
      operations:
      - method: GET
        name: listpercentagepromotions
        call: core-promotions.listpercentagepromotions
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createpercentagepromotion
        call: core-promotions.createpercentagepromotion
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /api/fixed_amount_promotions
      name: fixed-amount-promotions
      operations:
      - method: GET
        name: listfixedamountpromotions
        call: core-promotions.listfixedamountpromotions
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createfixedamountpromotion
        call: core-promotions.createfixedamountpromotion
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /api/free_shipping_promotions
      name: free-shipping-promotions
      operations:
      - method: GET
        name: listfreeshippingpromotions
        call: core-promotions.listfreeshippingpromotions
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createfreeshippingpromotion
        call: core-promotions.createfreeshippingpromotion
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /api/free_gift_promotions
      name: free-gift-promotions
      operations:
      - method: GET
        name: listfreegiftpromotions
        call: core-promotions.listfreegiftpromotions
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createfreegiftpromotion
        call: core-promotions.createfreegiftpromotion
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /api/buy_x_pay_y_promotions
      name: buy-x-pay-y-promotions
      operations:
      - method: GET
        name: listbuyxpayypromotions
        call: core-promotions.listbuyxpayypromotions
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createbuyxpayypromotion
        call: core-promotions.createbuyxpayypromotion
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /api/coupons
      name: coupons
      operations:
      - method: GET
        name: listcoupons
        call: core-promotions.listcoupons
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createcoupon
        call: core-promotions.createcoupon
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /api/gift_cards
      name: gift-cards
      operations:
      - method: GET
        name: listgiftcards
        call: core-promotions.listgiftcards
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: creategiftcard
        call: core-promotions.creategiftcard
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: core-promotions-mcp
    port: 9090
    transport: http
    description: MCP adapter for Commerce Layer Core API — Promotions.
    tools:
    - name: commerce-layer-listpromotions
      description: List All Promotions
      hints:
        readOnly: true
        idempotent: true
        destructive: false
      call: core-promotions.listpromotions
      outputParameters:
      - type: object
        mapping: $.
    - name: commerce-layer-listpercentagepromotions
      description: List All Percentage Discount Promotions
      hints:
        readOnly: true
        idempotent: true
        destructive: false
      call: core-promotions.listpercentagepromotions
      outputParameters:
      - type: object
        mapping: $.
    - name: commerce-layer-createpercentagepromotion
      description: Create A Percentage Discount Promotion
      hints:
        readOnly: false
        idempotent: false
        destructive: false
      call: core-promotions.createpercentagepromotion
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: commerce-layer-listfixedamountpromotions
      description: List All Fixed Amount Promotions
      hints:
        readOnly: true
        idempotent: true
        destructive: false
      call: core-promotions.listfixedamountpromotions
      outputParameters:
      - type: object
        mapping: $.
    - name: commerce-layer-createfixedamountpromotion
      description: Create A Fixed Amount Promotion
      hints:
        readOnly: false
        idempotent: false
        destructive: false
      call: core-promotions.createfixedamountpromotion
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: commerce-layer-listfreeshippingpromotions
      description: List All Free Shipping Promotions
      hints:
        readOnly: true
        idempotent: true
        destructive: false
      call: core-promotions.listfreeshippingpromotions
      outputParameters:
      - type: object
        mapping: $.
    - name: commerce-layer-createfreeshippingpromotion
      description: Create A Free Shipping Promotion
      hints:
        readOnly: false
        idempotent: false
        destructive: false
      call: core-promotions.createfreeshippingpromotion
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: commerce-layer-listfreegiftpromotions
      description: List All Free Gift Promotions
      hints:
        readOnly: true
        idempotent: true
        destructive: false
      call: core-promotions.listfreegiftpromotions
      outputParameters:
      - type: object
        mapping: $.
    - name: commerce-layer-createfreegiftpromotion
      description: Create A Free Gift Promotion
      hints:
        readOnly: false
        idempotent: false
        destructive: false
      call: core-promotions.createfreegiftpromotion
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: commerce-layer-listbuyxpayypromotions
      description: List All Buy X Pay Y Promotions
      hints:
        readOnly: true
        idempotent: true
        destructive: false
      call: core-promotions.listbuyxpayypromotions
      outputParameters:
      - type: object
        mapping: $.
    - name: commerce-layer-createbuyxpayypromotion
      description: Create A Buy X Pay Y Promotion
      hints:
        readOnly: false
        idempotent: false
        destructive: false
      call: core-promotions.createbuyxpayypromotion
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: commerce-layer-listcoupons
      description: List All Coupons
      hints:
        readOnly: true
        idempotent: true
        destructive: false
      call: core-promotions.listcoupons
      outputParameters:
      - type: object
        mapping: $.
    - name: commerce-layer-createcoupon
      description: Create A Coupon
      hints:
        readOnly: false
        idempotent: false
        destructive: false
      call: core-promotions.createcoupon
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: commerce-layer-listgiftcards
      description: List All Gift Cards
      hints:
        readOnly: true
        idempotent: true
        destructive: false
      call: core-promotions.listgiftcards
      outputParameters:
      - type: object
        mapping: $.
    - name: commerce-layer-creategiftcard
      description: Create A Gift Card
      hints:
        readOnly: false
        idempotent: false
        destructive: false
      call: core-promotions.creategiftcard
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.