SAP Commerce Cloud Promotions API

openapi: 3.2.0
info:
  title: SAP Commerce Cloud Commerce Web Services Promotions API
  description: RESTful OCC (Omni Commerce Connect) v2 API for SAP Commerce Cloud, providing commerce operations including product catalog browsing, cart management, checkout, order management, user account management, and store locator functionality. This API supports both B2B and B2C commerce scenarios.
  version: '2.0'
  contact:
    name: SAP Support
    url: https://support.sap.com/
  termsOfService: https://www.sap.com/about/legal/terms-of-use.html
servers:
- url: https://{tenant}.{region}.commercecloud.sap/occ/v2/{baseSiteId}
  description: SAP Commerce Cloud Production
  variables:
    tenant:
      description: Tenant identifier
      default: my-tenant
    region:
      description: Deployment region
      default: us
    baseSiteId:
      description: Base site identifier
      default: electronics
security:
- oauth2: []
tags:
- name: Promotions
  description: Promotions and vouchers
paths:
  /users/{userId}/carts/{cartId}/vouchers:
    get:
      operationId: getCartVouchers
      summary: SAP Commerce Cloud List applied vouchers
      description: Retrieve all vouchers applied to the cart.
      tags:
      - Promotions
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: '#/components/parameters/cartId'
      - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: Applied vouchers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoucherList'
    post:
      operationId: applyCartVoucher
      summary: SAP Commerce Cloud Apply voucher to cart
      description: Apply a voucher code to the cart.
      tags:
      - Promotions
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: '#/components/parameters/cartId'
      - name: voucherId
        in: query
        required: true
        description: Voucher code
        schema:
          type: string
      responses:
        '200':
          description: Voucher applied
        '400':
          description: Invalid voucher code
  /users/{userId}/carts/{cartId}/vouchers/{voucherId}:
    delete:
      operationId: removeCartVoucher
      summary: SAP Commerce Cloud Remove voucher from cart
      description: Remove a previously applied voucher from the cart.
      tags:
      - Promotions
      parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: '#/components/parameters/cartId'
      - name: voucherId
        in: path
        required: true
        description: Voucher code
        schema:
          type: string
      responses:
        '200':
          description: Voucher removed
        '404':
          description: Voucher not found on cart
components:
  parameters:
    cartId:
      name: cartId
      in: path
      required: true
      description: Cart identifier
      schema:
        type: string
    userId:
      name: userId
      in: path
      required: true
      description: User identifier. Use 'current' for the authenticated user or 'anonymous' for guest users.
      schema:
        type: string
    fields:
      name: fields
      in: query
      description: Response field configuration level. Use BASIC, DEFAULT, or FULL to control the amount of data returned.
      schema:
        type: string
        enum:
        - BASIC
        - DEFAULT
        - FULL
        default: DEFAULT
  schemas:
    Voucher:
      type: object
      properties:
        code:
          type: string
          description: Voucher code
        name:
          type: string
          description: Voucher name
        description:
          type: string
          description: Voucher description
        value:
          type: number
          format: double
          description: Voucher value
        valueFormatted:
          type: string
          description: Formatted voucher value
        voucherCode:
          type: string
          description: Applied voucher code
        freeShipping:
          type: boolean
          description: Whether voucher provides free shipping
    VoucherList:
      type: object
      properties:
        vouchers:
          type: array
          items:
            $ref: '#/components/schemas/Voucher'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication for SAP Commerce Cloud
      flows:
        clientCredentials:
          tokenUrl: https://{tenant}.{region}.commercecloud.sap/authorizationserver/oauth/token
          scopes:
            basic: Basic access
        password:
          tokenUrl: https://{tenant}.{region}.commercecloud.sap/authorizationserver/oauth/token
          scopes:
            basic: Basic access
externalDocs:
  description: SAP Commerce Cloud OCC API Documentation
  url: https://help.sap.com/docs/SAP_COMMERCE/d0224eca81e249cb821f2cdf45a82ace/8c19398686691014a8c0fd6c3e5d44a0.html