VTex Promotions & Taxes API v2 — Coupons

naftiko: 1.0.0-alpha2
info:
  label: VTex Promotions & Taxes API v2 — Coupons
  description: 'VTex Promotions & Taxes API v2 — Coupons. 10 operations. Lead operation: VTex Get coupons. Self-contained
    Naftiko capability covering one Vtex business surface.'
  tags:
  - Vtex
  - Coupons
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    VTEX_API_KEY: VTEX_API_KEY
capability:
  consumes:
  - type: http
    namespace: promotions-taxes-coupons
    baseUri: https://{accountName}.{environment}.com.br
    description: VTex Promotions & Taxes API v2 — Coupons business capability. Self-contained, no shared references.
    resources:
    - name: api-rnb-v2-pvt-coupon
      path: /api/rnb/v2/pvt/coupon
      operations:
      - name: getgroupedcoupons
        method: GET
        description: VTex Get coupons
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Describes the type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
    - name: api-rnb-v2-pvt-coupon-group
      path: /api/rnb/v2/pvt/coupon/group
      operations:
      - name: creategroupsofcoupons
        method: POST
        description: VTex Create coupon batches
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Describes the type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-rnb-v2-pvt-coupon-group-archived
      path: /api/rnb/v2/pvt/coupon/group/archived
      operations:
      - name: getgroupedarchivedcoupons
        method: GET
        description: VTex Get archived coupons
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Describes the type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
    - name: api-rnb-v2-pvt-coupon-group-groupingKey
      path: /api/rnb/v2/pvt/coupon/group/{groupingKey}
      operations:
      - name: getcoupongroupinformation
        method: GET
        description: VTex Get coupon batch information
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Describes the type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: groupingKey
          in: path
          type: string
          description: Coupon grouping key, which is the prefix for the coupon batch's generated codes.
          required: true
      - name: editcoupongroupconfiguration
        method: PUT
        description: VTex Edit coupon batch configuration
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Describes the type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: groupingKey
          in: path
          type: string
          description: Coupon grouping key, which is the prefix for the coupon batch's generated codes.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-rnb-v2-pvt-coupon-group-groupingKey-archive
      path: /api/rnb/v2/pvt/coupon/group/{groupingKey}/archive
      operations:
      - name: archivedcoupongroup
        method: PUT
        description: VTex Archive a coupon batch
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Describes the type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: groupingKey
          in: path
          type: string
          description: Coupon grouping key, which is the prefix for the coupon batch's generated codes.
          required: true
    - name: api-rnb-v2-pvt-coupon-group-groupingKey-codes
      path: /api/rnb/v2/pvt/coupon/group/{groupingKey}/codes
      operations:
      - name: getcoupongroupcodes
        method: GET
        description: VTex Get coupon batch codes
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Describes the type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: groupingKey
          in: path
          type: string
          description: Coupon grouping key, which is the prefix for the coupon batch's generated codes.
          required: true
    - name: api-rnb-v2-pvt-coupon-group-groupingKey-unarchive
      path: /api/rnb/v2/pvt/coupon/group/{groupingKey}/unarchive
      operations:
      - name: unarchivedcoupongroup
        method: PUT
        description: VTex Unarchive a coupon batch
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Describes the type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: groupingKey
          in: path
          type: string
          description: Coupon grouping key, which is the prefix for the coupon batch's generated codes.
          required: true
    - name: api-rnb-v2-pvt-coupon-usage-count-group-groupingKey
      path: /api/rnb/v2/pvt/coupon/usage-count/group/{groupingKey}
      operations:
      - name: getnumberofusagesofacouponbatch
        method: GET
        description: VTex Get usage count for a coupon batch
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Describes the type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: groupingKey
          in: path
          type: string
          description: Coupon grouping key, which is the prefix for the coupon batch's generated codes.
          required: true
    - name: api-rnb-v2-pvt-coupon-usage-count-couponCode
      path: /api/rnb/v2/pvt/coupon/usage-count/{couponCode}
      operations:
      - name: getnumberofusagesofasinglecoupon
        method: GET
        description: VTex Get usage count for a single coupon
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: Content-Type
          in: header
          type: string
          description: Describes the type of the content being sent.
          required: true
        - name: Accept
          in: header
          type: string
          description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
          required: true
        - name: couponCode
          in: path
          type: string
          description: Single coupon code.
          required: true
    authentication:
      type: apikey
      key: X-VTEX-API-AppKey
      value: '{{env.VTEX_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: promotions-taxes-coupons-rest
    port: 8080
    description: REST adapter for VTex Promotions & Taxes API v2 — Coupons. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/api/rnb/v2/pvt/coupon
      name: api-rnb-v2-pvt-coupon
      description: REST surface for api-rnb-v2-pvt-coupon.
      operations:
      - method: GET
        name: getgroupedcoupons
        description: VTex Get coupons
        call: promotions-taxes-coupons.getgroupedcoupons
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/rnb/v2/pvt/coupon/group
      name: api-rnb-v2-pvt-coupon-group
      description: REST surface for api-rnb-v2-pvt-coupon-group.
      operations:
      - method: POST
        name: creategroupsofcoupons
        description: VTex Create coupon batches
        call: promotions-taxes-coupons.creategroupsofcoupons
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/rnb/v2/pvt/coupon/group/archived
      name: api-rnb-v2-pvt-coupon-group-archived
      description: REST surface for api-rnb-v2-pvt-coupon-group-archived.
      operations:
      - method: GET
        name: getgroupedarchivedcoupons
        description: VTex Get archived coupons
        call: promotions-taxes-coupons.getgroupedarchivedcoupons
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/rnb/v2/pvt/coupon/group/{groupingkey}
      name: api-rnb-v2-pvt-coupon-group-groupingkey
      description: REST surface for api-rnb-v2-pvt-coupon-group-groupingKey.
      operations:
      - method: GET
        name: getcoupongroupinformation
        description: VTex Get coupon batch information
        call: promotions-taxes-coupons.getcoupongroupinformation
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          groupingKey: rest.groupingKey
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: editcoupongroupconfiguration
        description: VTex Edit coupon batch configuration
        call: promotions-taxes-coupons.editcoupongroupconfiguration
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          groupingKey: rest.groupingKey
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/rnb/v2/pvt/coupon/group/{groupingkey}/archive
      name: api-rnb-v2-pvt-coupon-group-groupingkey-archive
      description: REST surface for api-rnb-v2-pvt-coupon-group-groupingKey-archive.
      operations:
      - method: PUT
        name: archivedcoupongroup
        description: VTex Archive a coupon batch
        call: promotions-taxes-coupons.archivedcoupongroup
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          groupingKey: rest.groupingKey
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/rnb/v2/pvt/coupon/group/{groupingkey}/codes
      name: api-rnb-v2-pvt-coupon-group-groupingkey-codes
      description: REST surface for api-rnb-v2-pvt-coupon-group-groupingKey-codes.
      operations:
      - method: GET
        name: getcoupongroupcodes
        description: VTex Get coupon batch codes
        call: promotions-taxes-coupons.getcoupongroupcodes
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          groupingKey: rest.groupingKey
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/rnb/v2/pvt/coupon/group/{groupingkey}/unarchive
      name: api-rnb-v2-pvt-coupon-group-groupingkey-unarchive
      description: REST surface for api-rnb-v2-pvt-coupon-group-groupingKey-unarchive.
      operations:
      - method: PUT
        name: unarchivedcoupongroup
        description: VTex Unarchive a coupon batch
        call: promotions-taxes-coupons.unarchivedcoupongroup
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          groupingKey: rest.groupingKey
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/rnb/v2/pvt/coupon/usage-count/group/{groupingkey}
      name: api-rnb-v2-pvt-coupon-usage-count-group-groupingkey
      description: REST surface for api-rnb-v2-pvt-coupon-usage-count-group-groupingKey.
      operations:
      - method: GET
        name: getnumberofusagesofacouponbatch
        description: VTex Get usage count for a coupon batch
        call: promotions-taxes-coupons.getnumberofusagesofacouponbatch
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          groupingKey: rest.groupingKey
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/rnb/v2/pvt/coupon/usage-count/{couponcode}
      name: api-rnb-v2-pvt-coupon-usage-count-couponcode
      description: REST surface for api-rnb-v2-pvt-coupon-usage-count-couponCode.
      operations:
      - method: GET
        name: getnumberofusagesofasinglecoupon
        description: VTex Get usage count for a single coupon
        call: promotions-taxes-coupons.getnumberofusagesofasinglecoupon
        with:
          Content-Type: rest.Content-Type
          Accept: rest.Accept
          couponCode: rest.couponCode
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: promotions-taxes-coupons-mcp
    port: 9090
    transport: http
    description: MCP adapter for VTex Promotions & Taxes API v2 — Coupons. One tool per consumed operation, routed inline
      through this capability's consumes block.
    tools:
    - name: vtex-get-coupons
      description: VTex Get coupons
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: promotions-taxes-coupons.getgroupedcoupons
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-create-coupon-batches
      description: VTex Create coupon batches
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: promotions-taxes-coupons.creategroupsofcoupons
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-get-archived-coupons
      description: VTex Get archived coupons
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: promotions-taxes-coupons.getgroupedarchivedcoupons
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-get-coupon-batch-information
      description: VTex Get coupon batch information
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: promotions-taxes-coupons.getcoupongroupinformation
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        groupingKey: tools.groupingKey
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-edit-coupon-batch-configuration
      description: VTex Edit coupon batch configuration
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: promotions-taxes-coupons.editcoupongroupconfiguration
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        groupingKey: tools.groupingKey
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-archive-coupon-batch
      description: VTex Archive a coupon batch
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: promotions-taxes-coupons.archivedcoupongroup
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        groupingKey: tools.groupingKey
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-get-coupon-batch-codes
      description: VTex Get coupon batch codes
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: promotions-taxes-coupons.getcoupongroupcodes
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        groupingKey: tools.groupingKey
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-unarchive-coupon-batch
      description: VTex Unarchive a coupon batch
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: promotions-taxes-coupons.unarchivedcoupongroup
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        groupingKey: tools.groupingKey
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-get-usage-count-coupon
      description: VTex Get usage count for a coupon batch
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: promotions-taxes-coupons.getnumberofusagesofacouponbatch
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        groupingKey: tools.groupingKey
      outputParameters:
      - type: object
        mapping: $.
    - name: vtex-get-usage-count-single
      description: VTex Get usage count for a single coupon
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: promotions-taxes-coupons.getnumberofusagesofasinglecoupon
      with:
        Content-Type: tools.Content-Type
        Accept: tools.Accept
        couponCode: tools.couponCode
      outputParameters:
      - type: object
        mapping: $.