sitecore Buyers API

openapi: 3.2.0
info:
  title: Sitecore OrderCloud Buyers 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: 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:
  schemas:
    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
    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
    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'
    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
  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
    buyerID:
      name: buyerID
      in: path
      description: The unique identifier of the buyer organization
      required: true
      schema:
        type: string
    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'
    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