sitecore Buyers API

openapi: 3.1.0
info:
  title: Sitecore CDP REST Audit Buyers 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: Buyers
  description: Endpoints for managing buyer organizations and their associated users, user groups, addresses, credit cards, spending accounts, cost centers, and approval rules.
paths:
  /buyers:
    get:
      operationId: listBuyers
      summary: List buyers
      description: Retrieves a paginated list of buyer organizations. Buyers represent customer-facing organizations with their own users, catalogs, and purchasing contexts. Supports filtering, sorting, and pagination.
      tags:
      - Buyers
      parameters:
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/sortBy'
      responses:
        '200':
          description: A paginated list of buyers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createBuyer
      summary: Create a buyer
      description: Creates a new buyer organization. Buyers represent storefront customer organizations and can be associated with catalogs, user groups, and approval workflows.
      tags:
      - Buyers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBuyerRequest'
      responses:
        '201':
          description: Buyer created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Buyer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /buyers/{buyerID}:
    get:
      operationId: getBuyer
      summary: Get a buyer
      description: Retrieves a specific buyer organization by its identifier. Returns full buyer configuration including active status, default catalog, and extended properties.
      tags:
      - Buyers
      parameters:
      - $ref: '#/components/parameters/buyerID'
      responses:
        '200':
          description: Buyer details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Buyer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateBuyer
      summary: Update a buyer
      description: Performs a full replacement update of a buyer organization. All fields are replaced with the values in the request body.
      tags:
      - Buyers
      parameters:
      - $ref: '#/components/parameters/buyerID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBuyerRequest'
      responses:
        '200':
          description: Buyer updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Buyer'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteBuyer
      summary: Delete a buyer
      description: Permanently deletes a buyer organization and all associated resources including users, user groups, and addresses.
      tags:
      - Buyers
      parameters:
      - $ref: '#/components/parameters/buyerID'
      responses:
        '204':
          description: Buyer deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    buyerID:
      name: buyerID
      in: path
      description: The unique identifier of the buyer organization
      required: true
      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
    search:
      name: search
      in: query
      description: Full-text search term to filter results
      required: false
      schema:
        type: string
  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'
    NotFound:
      description: The requested resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    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
    Buyer:
      type: object
      description: A buyer organization in the OrderCloud marketplace
      properties:
        ID:
          type: string
          description: The unique identifier of the buyer organization
        Name:
          type: string
          description: The display name of the buyer organization
        DefaultCatalogID:
          type: string
          description: The identifier of the buyer's default product catalog
        Active:
          type: boolean
          description: Whether the buyer organization is active
        xp:
          type: object
          description: Extended properties for custom buyer 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
    CreateBuyerRequest:
      type: object
      description: Request body for creating or updating a buyer
      required:
      - Name
      properties:
        ID:
          type: string
          description: Optional custom identifier for the buyer
        Name:
          type: string
          description: The display name of the buyer organization
        DefaultCatalogID:
          type: string
          description: The identifier of the default catalog to assign
        Active:
          type: boolean
          description: Whether the buyer should be active on creation
          default: true
        xp:
          type: object
          description: Extended properties for custom buyer attributes
          additionalProperties: true
    BuyerListResponse:
      type: object
      description: A paginated list of buyers
      properties:
        Meta:
          $ref: '#/components/schemas/ListMetadata'
        Items:
          type: array
          description: The buyers for the current page
          items:
            $ref: '#/components/schemas/Buyer'
  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