sitecore Promotions API

openapi: 3.1.0
info:
  title: Sitecore CDP REST Audit Promotions API
  description: The Sitecore CDP REST API provides synchronous access to retrieve, create, update, and delete data stored in Sitecore Customer Data Platform. It exposes guest profiles, orders, order items, order contacts, order consumers, and data extensions through standard HTTP methods. Developers use this API to build integrations that read or write customer data programmatically, enabling use cases such as audience segmentation, data enrichment, and reporting. Authentication uses HTTP Basic Auth with a client key and API token obtained from the CDP instance settings. Regional server endpoints must be used based on the CDP instance's geographic deployment.
  version: v2.1
  contact:
    name: Sitecore Support
    url: https://www.sitecore.com/support
  termsOfService: https://www.sitecore.com/legal/terms-of-service
servers:
- url: https://api-engage-eu.sitecorecloud.io
  description: EU Production Server
- url: https://api-engage-us.sitecorecloud.io
  description: US Production Server
- url: https://api-engage-ap.sitecorecloud.io
  description: Asia-Pacific Production Server
- url: https://api-engage-jpe.sitecorecloud.io
  description: Japan Production Server
security:
- basicAuth: []
tags:
- name: Promotions
  description: Endpoints for creating and managing discount promotions and coupon codes that can be applied to orders at checkout.
paths:
  /promotions:
    get:
      operationId: listPromotions
      summary: List promotions
      description: Retrieves a paginated list of promotions. Promotions define discount rules, coupon codes, eligibility requirements, and usage limits.
      tags:
      - Promotions
      parameters:
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: A paginated list of promotions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromotionListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPromotion
      summary: Create a promotion
      description: Creates a new promotion with discount rules, an optional coupon code, eligibility criteria, and usage limits. Promotions can be applied to orders at checkout.
      tags:
      - Promotions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePromotionRequest'
      responses:
        '201':
          description: Promotion created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Promotion'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Authentication token is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: The request body or parameters are invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    Promotion:
      type: object
      description: A discount promotion that can be applied to orders
      properties:
        ID:
          type: string
          description: The unique identifier of the promotion
        Code:
          type: string
          description: The coupon code customers enter to apply the promotion
        Name:
          type: string
          description: The display name of the promotion
        Description:
          type: string
          description: A description of the promotion
        Active:
          type: boolean
          description: Whether the promotion is currently active
        StartDate:
          type: string
          description: The ISO 8601 start date for the promotion
          format: date-time
        ExpirationDate:
          type: string
          description: The ISO 8601 expiration date for the promotion
          format: date-time
        Value:
          type: number
          description: The discount value (amount or percentage based on type)
          format: float
        xp:
          type: object
          description: Extended properties for custom promotion attributes
          additionalProperties: true
    ErrorResponse:
      type: object
      description: An error response body
      properties:
        Errors:
          type: array
          description: List of error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
    ListMetadata:
      type: object
      description: Pagination metadata for list responses
      properties:
        Page:
          type: integer
          description: The current page number (1-indexed)
        PageSize:
          type: integer
          description: The number of items per page
        TotalCount:
          type: integer
          description: The total number of items matching the query
        TotalPages:
          type: integer
          description: The total number of pages
        ItemRange:
          type: array
          description: The inclusive range [start, end] of item indexes for this page
          items:
            type: integer
    PromotionListResponse:
      type: object
      description: A paginated list of promotions
      properties:
        Meta:
          $ref: '#/components/schemas/ListMetadata'
        Items:
          type: array
          description: The promotions for the current page
          items:
            $ref: '#/components/schemas/Promotion'
    ErrorDetail:
      type: object
      description: A single error detail
      properties:
        ErrorCode:
          type: string
          description: The machine-readable error code
        Message:
          type: string
          description: A human-readable description of the error
        Data:
          type: object
          description: Additional data about the error context
          additionalProperties: true
    CreatePromotionRequest:
      type: object
      description: Request body for creating a promotion
      required:
      - Code
      - Value
      properties:
        ID:
          type: string
          description: Optional custom identifier for the promotion
        Code:
          type: string
          description: The coupon code for the promotion
        Name:
          type: string
          description: The display name of the promotion
        Description:
          type: string
          description: A description of the promotion
        Active:
          type: boolean
          description: Whether the promotion should be active
          default: true
        StartDate:
          type: string
          description: The ISO 8601 start date
          format: date-time
        ExpirationDate:
          type: string
          description: The ISO 8601 expiration date
          format: date-time
        Value:
          type: number
          description: The discount value
          format: float
        xp:
          type: object
          description: Extended properties for custom promotion attributes
          additionalProperties: true
  parameters:
    pageSize:
      name: pageSize
      in: query
      description: Number of items to return per page (max 100)
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    page:
      name: page
      in: query
      description: Page number to retrieve (1-indexed)
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
    search:
      name: search
      in: query
      description: Full-text search term to filter results
      required: false
      schema:
        type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using a client key as the username and an API token as the password. Credentials are obtained from Sitecore CDP Settings > API access.
externalDocs:
  description: Sitecore CDP REST API Documentation
  url: https://doc.sitecore.com/cdp/en/developers/api/rest-apis.html