sitecore Order Items API

openapi: 3.2.0
info:
  title: Sitecore CDP REST Order Items 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: Order Items
  description: Endpoints for managing individual line items within guest orders, including product references, quantities, and pricing information.
paths:
  /v2.1/guests/{guestRef}/orders/{orderRef}/items:
    get:
      operationId: listOrderItems
      summary: List order items
      description: Retrieves all line items within a specific order. Each item represents a product included in the order with its quantity and pricing.
      tags:
      - Order Items
      parameters:
      - $ref: '#/components/parameters/guestRef'
      - $ref: '#/components/parameters/orderRef'
      responses:
        '200':
          description: List of order items
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrderItem'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createOrderItem
      summary: Create an order item
      description: Adds a new line item to an existing order. Each item references a product and includes quantity and pricing information.
      tags:
      - Order Items
      parameters:
      - $ref: '#/components/parameters/guestRef'
      - $ref: '#/components/parameters/orderRef'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderItemRequest'
      responses:
        '201':
          description: Order item created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    guestRef:
      name: guestRef
      in: path
      description: The unique reference identifier for the guest profile
      required: true
      schema:
        type: string
    orderRef:
      name: orderRef
      in: path
      description: The unique reference identifier for the order
      required: true
      schema:
        type: string
  schemas:
    CreateOrderItemRequest:
      type: object
      description: Request body for adding a line item to an order
      required:
      - sku
      - quantity
      properties:
        sku:
          type: string
          description: The product SKU or identifier
        name:
          type: string
          description: The product name
        quantity:
          type: integer
          description: The quantity of this product purchased
          minimum: 1
        price:
          type: number
          description: The unit price of the product
          format: float
    ErrorResponse:
      type: object
      description: An error response body
      properties:
        message:
          type: string
          description: A human-readable error message
        statusCode:
          type: integer
          description: The HTTP status code
        errors:
          type: array
          description: List of detailed error messages
          items:
            type: string
    OrderItem:
      type: object
      description: A line item within an order representing a purchased product
      properties:
        itemRef:
          type: string
          description: The unique reference identifier for the order item
        sku:
          type: string
          description: The product SKU or identifier
        name:
          type: string
          description: The product name
        quantity:
          type: integer
          description: The quantity of this product purchased
          minimum: 1
        price:
          type: number
          description: The unit price of the product
          format: float
        totalPrice:
          type: number
          description: The total price for this line item (quantity * price)
          format: float
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found
      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:
    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