sitecore Promotions API

openapi: 3.2.0
info:
  title: Sitecore OrderCloud Promotions API
  description: The Sitecore OrderCloud API is a headless, API-first commerce platform providing RESTful endpoints for managing the full range of e-commerce operations including products, catalogs, orders, buyers, sellers, promotions, and fulfillment. It is designed to support B2C, B2B, and B2B2C commerce models with a highly flexible and extensible data model that allows custom extended properties (xp) on most resources. The API uses OAuth 2.0 for authentication and supports granular role-based access control for different buyer, seller, and supplier contexts. All responses are in JSON and the API supports filtering, sorting, searching, and pagination on list endpoints.
  version: v1
  contact:
    name: Sitecore OrderCloud Support
    url: https://ordercloud.io/contact
  termsOfService: https://ordercloud.io/terms-of-service
servers:
- url: https://api.ordercloud.io/v1
  description: OrderCloud Production Server
security:
- bearerAuth: []
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:
  schemas:
    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
    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
    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
    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
    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'
  parameters:
    search:
      name: search
      in: query
      description: Full-text search term to filter results
      required: false
      schema:
        type: string
    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
  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'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 bearer token obtained from https://auth.ordercloud.io/oauth/token. The token scope determines accessible resources based on assigned roles.
externalDocs:
  description: Sitecore OrderCloud API Reference
  url: https://api-docs.sitecore.com/ordercloud