openapi: 3.1.0
info:
  title: SAP Commerce Cloud Admin Addresses Promotions API
  description: Administrative API for SAP Commerce Cloud providing system configuration, maintenance, monitoring, and health check capabilities. Enables programmatic access to system administration functions including cache management, CronJob execution, and system health monitoring.
  version: '1.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
  description: SAP Commerce Cloud Production
  variables:
    tenant:
      description: Tenant identifier
      default: my-tenant
    region:
      description: Deployment region
      default: us
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:
    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
    userId:
      name: userId
      in: path
      required: true
      description: User identifier. Use 'current' for the authenticated user or 'anonymous' for guest users.
      schema:
        type: string
    cartId:
      name: cartId
      in: path
      required: true
      description: Cart identifier
      schema:
        type: string
  schemas:
    VoucherList:
      type: object
      properties:
        vouchers:
          type: array
          items:
            $ref: '#/components/schemas/Voucher'
    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
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication for SAP Commerce Cloud Admin API
      flows:
        clientCredentials:
          tokenUrl: https://{tenant}.{region}.commercecloud.sap/authorizationserver/oauth/token
          scopes:
            admin: Administrative access
externalDocs:
  description: SAP Commerce Cloud Administration Documentation
  url: https://help.sap.com/docs/SAP_COMMERCE_CLOUD_PUBLIC_CLOUD/