sitecore Products API

openapi: 3.2.0
info:
  title: Sitecore OrderCloud Products 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: Products
  description: Endpoints for creating, retrieving, updating, and deleting products within the OrderCloud catalog. Products support extended properties, variants, specs, and inventory tracking.
paths:
  /products:
    get:
      operationId: listProducts
      summary: List products
      description: Retrieves a paginated list of products from the OrderCloud catalog. Supports full-text search, filtering by any product field, sorting, and pagination. Results include product metadata, pricing references, and extended properties.
      tags:
      - Products
      parameters:
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/sortBy'
      - name: catalogID
        in: query
        description: Filter products by catalog identifier
        required: false
        schema:
          type: string
      - name: categoryID
        in: query
        description: Filter products by category identifier
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A paginated list of products
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createProduct
      summary: Create a product
      description: Creates a new product in the OrderCloud catalog. Products support flexible extended properties (xp), variant generation via specs, and inventory tracking. Products must be assigned to a catalog before buyers can see or purchase them.
      tags:
      - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProductRequest'
      responses:
        '201':
          description: Product created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /products/{productID}:
    get:
      operationId: getProduct
      summary: Get a product
      description: Retrieves a specific product by its identifier. Returns full product details including description, price schedule assignment, inventory configuration, and extended properties.
      tags:
      - Products
      parameters:
      - $ref: '#/components/parameters/productID'
      responses:
        '200':
          description: Product details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateProduct
      summary: Update a product
      description: Performs a full replacement update of a product. All fields are replaced with the values in the request body. Use PATCH for partial updates.
      tags:
      - Products
      parameters:
      - $ref: '#/components/parameters/productID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProductRequest'
      responses:
        '200':
          description: Product updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: patchProduct
      summary: Partially update a product
      description: Performs a partial update of a product. Only the fields provided in the request body are updated; all other fields retain their current values.
      tags:
      - Products
      parameters:
      - $ref: '#/components/parameters/productID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProductRequest'
      responses:
        '200':
          description: Product partially updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteProduct
      summary: Delete a product
      description: Permanently deletes a product from the catalog. All catalog assignments and buyer visibility are also removed.
      tags:
      - Products
      parameters:
      - $ref: '#/components/parameters/productID'
      responses:
        '204':
          description: Product deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Product:
      type: object
      description: A product available for purchase within the OrderCloud catalog
      properties:
        ID:
          type: string
          description: The unique identifier of the product
        Name:
          type: string
          description: The display name of the product
        Description:
          type: string
          description: The detailed description of the product
        QuantityMultiplier:
          type: integer
          description: The minimum purchase quantity increment for this product
          default: 1
        ShipWeight:
          type: number
          description: The shipping weight of the product in pounds
          format: float
        ShipHeight:
          type: number
          description: The shipping height of the product in inches
          format: float
        ShipWidth:
          type: number
          description: The shipping width of the product in inches
          format: float
        ShipLength:
          type: number
          description: The shipping length of the product in inches
          format: float
        Active:
          type: boolean
          description: Whether the product is active and visible to buyers
        DefaultPriceScheduleID:
          type: string
          description: The identifier of the default price schedule for this product
        Inventory:
          $ref: '#/components/schemas/Inventory'
        xp:
          type: object
          description: Extended properties for custom product attributes
          additionalProperties: true
    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
    CreateProductRequest:
      type: object
      description: Request body for creating or updating a product
      required:
      - Name
      properties:
        ID:
          type: string
          description: Optional custom identifier for the product
        Name:
          type: string
          description: The display name of the product
        Description:
          type: string
          description: The detailed description of the product
        Active:
          type: boolean
          description: Whether the product should be active
          default: false
        DefaultPriceScheduleID:
          type: string
          description: The identifier of the default price schedule
        xp:
          type: object
          description: Extended properties for custom product attributes
          additionalProperties: true
    ProductListResponse:
      type: object
      description: A paginated list of products
      properties:
        Meta:
          $ref: '#/components/schemas/ListMetadata'
        Items:
          type: array
          description: The products for the current page
          items:
            $ref: '#/components/schemas/Product'
    Inventory:
      type: object
      description: Inventory tracking configuration for a product
      properties:
        Enabled:
          type: boolean
          description: Whether inventory tracking is enabled for this product
        VariantLevelTracking:
          type: boolean
          description: Whether inventory is tracked at the variant level
        OrderCanExceed:
          type: boolean
          description: Whether orders can be placed when inventory is insufficient
        QuantityAvailable:
          type: integer
          description: The current available inventory quantity
        LastUpdated:
          type: string
          description: The ISO 8601 timestamp of the last inventory update
          format: date-time
  parameters:
    search:
      name: search
      in: query
      description: Full-text search term to filter results
      required: false
      schema:
        type: string
    sortBy:
      name: sortBy
      in: query
      description: Field name to sort results by; prefix with ! to sort descending
      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
    productID:
      name: productID
      in: path
      description: The unique identifier of the product
      required: true
      schema:
        type: string
  responses:
    Unauthorized:
      description: Authentication token is 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:
    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