commercetools Inventory API

openapi: 3.1.0
info:
  title: commercetools Change History Carts Inventory API
  description: The commercetools Change History API provides a queryable audit log of all changes made to resources within a Composable Commerce project. It records mutations applied to resources such as products, orders, customers, discounts, and carts, along with metadata about who made the change and when. The API is hosted on separate regional endpoints from the main HTTP API and supports filtering by resource type, date range, user, and API client. It is useful for compliance workflows, debugging unexpected state changes, and building audit trails for regulated industries.
  version: '1.0'
  contact:
    name: commercetools Support
    url: https://support.commercetools.com
  termsOfService: https://commercetools.com/terms-conditions
servers:
- url: https://history.{region}.commercetools.com
  description: Production Change History Server
  variables:
    region:
      default: us-central1.gcp
      enum:
      - us-central1.gcp
      - us-east-2.aws
      - europe-west1.gcp
      - eu-central-1.aws
      - australia-southeast1.gcp
      description: The deployment region.
security:
- bearerAuth: []
tags:
- name: Inventory
  description: Manage inventory entries tracking stock levels per channel and SKU.
paths:
  /{projectKey}/inventory:
    get:
      operationId: listInventoryEntries
      summary: List inventory entries
      description: Returns a paginated list of inventory entries. Each entry tracks the available quantity and restockable quantity for a specific SKU, optionally scoped to a supply channel. Supports filtering and sorting.
      tags:
      - Inventory
      parameters:
      - $ref: '#/components/parameters/projectKey'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/where'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: A paged list of inventory entries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryPagedQueryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createInventoryEntry
      summary: Create an inventory entry
      description: Creates a new inventory entry for a given SKU. The entry can be scoped to a supply channel for multi-warehouse tracking. Optionally set expected delivery dates and restockable quantities.
      tags:
      - Inventory
      parameters:
      - $ref: '#/components/parameters/projectKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryEntryDraft'
      responses:
        '201':
          description: The created inventory entry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryEntry'
        '400':
          $ref: '#/components/responses/BadRequest'
  /{projectKey}/inventories/import-containers/{importContainerKey}:
    post:
      operationId: importInventoryEntries
      summary: Import inventory entries
      description: Submits a batch of inventory entry import requests for asynchronous processing. Inventory entries are matched by SKU and supply channel for upsert behavior.
      tags:
      - Inventory
      parameters:
      - $ref: '#/components/parameters/projectKey_2'
      - $ref: '#/components/parameters/importContainerKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryImportRequest'
      responses:
        '201':
          description: The import request was accepted for processing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResponse'
        '400':
          $ref: '#/components/responses/BadRequest_2'
components:
  schemas:
    InventoryImportRequest:
      type: object
      description: A batch of inventory entry resources to import.
      required:
      - type
      - resources
      properties:
        type:
          type: string
          enum:
          - inventory
          description: The resource type identifier.
        resources:
          type: array
          maxItems: 20
          items:
            $ref: '#/components/schemas/InventoryImport'
          description: Up to 20 inventory entry resources.
    ErrorObject:
      type: object
      description: An error object describing a validation or processing failure.
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Machine-readable error code.
        message:
          type: string
          description: Human-readable description of the error.
    Reference:
      type: object
      description: A reference to another resource by its typeId and id.
      required:
      - typeId
      - id
      properties:
        typeId:
          type: string
          description: The type identifier of the referenced resource (e.g., 'product', 'category').
        id:
          type: string
          description: The system-generated unique identifier of the referenced resource.
    InventoryEntry:
      type: object
      description: An inventory entry tracking available quantity for a specific SKU, optionally scoped to a supply channel.
      required:
      - id
      - version
      - sku
      - quantityOnStock
      - availableQuantity
      properties:
        id:
          type: string
          description: System-generated unique identifier.
        version:
          type: integer
          description: Current version for optimistic concurrency control.
        key:
          type: string
          description: User-defined unique identifier.
        sku:
          type: string
          description: SKU of the product variant this inventory entry tracks.
        supplyChannel:
          $ref: '#/components/schemas/Reference'
        quantityOnStock:
          type: integer
          description: Total quantity physically in stock.
        availableQuantity:
          type: integer
          description: Quantity available for ordering (stock minus reservations).
        restockableInDays:
          type: integer
          description: Expected days until out-of-stock items are restocked.
        expectedDelivery:
          type: string
          format: date-time
          description: Expected delivery date for restocking.
    InventoryPagedQueryResponse:
      type: object
      description: Paginated response containing a list of inventory entries.
      required:
      - limit
      - offset
      - count
      - total
      - results
      properties:
        limit:
          type: integer
        offset:
          type: integer
        count:
          type: integer
        total:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/InventoryEntry'
    ImportResponse:
      type: object
      description: The response returned after submitting an import request batch.
      required:
      - operationStatus
      properties:
        operationStatus:
          type: array
          items:
            $ref: '#/components/schemas/ImportOperationStatus'
          description: Status records for each resource in the submitted batch.
    ImportOperationStatus:
      type: object
      description: The initial status of a single resource submission in an import batch.
      required:
      - resourceKey
      - state
      properties:
        resourceKey:
          type: string
          description: User-defined key of the resource submitted.
        state:
          type: string
          enum:
          - Accepted
          - ValidationFailed
          description: Initial state of the operation after submission.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorObject'
          description: Immediate validation errors if the resource failed submission.
    InventoryEntryDraft:
      type: object
      description: Request body for creating a new inventory entry.
      required:
      - sku
      - quantityOnStock
      properties:
        key:
          type: string
          description: User-defined unique identifier.
        sku:
          type: string
          description: SKU of the product variant to track.
        supplyChannel:
          $ref: '#/components/schemas/Reference'
        quantityOnStock:
          type: integer
          description: Initial quantity on stock.
        restockableInDays:
          type: integer
          description: Expected restocking time in days.
        expectedDelivery:
          type: string
          format: date-time
          description: Expected delivery date for restocking.
    InventoryImport:
      type: object
      description: A single inventory entry resource for import.
      required:
      - key
      - sku
      - quantityOnStock
      properties:
        key:
          type: string
          description: User-defined key for matching against existing inventory entries.
        sku:
          type: string
          description: SKU of the product variant.
        quantityOnStock:
          type: integer
          description: Quantity on stock to set.
        supplyChannel:
          type: object
          description: Reference to the supply channel by key.
        restockableInDays:
          type: integer
          description: Expected restocking time in days.
  responses:
    BadRequest_2:
      description: The request was malformed or contained invalid parameters.
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
              message:
                type: string
    Unauthorized:
      description: The request lacked valid authentication credentials.
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
              message:
                type: string
    BadRequest:
      description: The request was malformed or contained invalid parameters.
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
              message:
                type: string
              errors:
                type: array
                items:
                  type: object
  parameters:
    projectKey:
      name: projectKey
      in: path
      required: true
      schema:
        type: string
      description: The unique key identifying the commercetools project.
    where:
      name: where
      in: query
      required: false
      schema:
        type: string
      description: Query predicate string for filtering results. Uses commercetools predicate syntax (e.g., 'customerEmail = "user@example.com"').
    importContainerKey:
      name: importContainerKey
      in: path
      required: true
      schema:
        type: string
      description: The user-defined key of the import container.
    projectKey_2:
      name: projectKey
      in: path
      required: true
      schema:
        type: string
      description: The unique key of the commercetools project.
    expand:
      name: expand
      in: query
      required: false
      schema:
        type: string
      description: Reference expansion path to inline referenced resources in the response (e.g., 'productType', 'categories[*]').
    offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        minimum: 0
        maximum: 10000
        default: 0
      description: Number of results to skip for pagination. Maximum 10000.
    limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 20
      description: Maximum number of results to return. Defaults to 20, maximum 500.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token obtained from the commercetools authentication service using client credentials flow. Requires the view_audit_log scope.
externalDocs:
  description: commercetools Change History API Documentation
  url: https://docs.commercetools.com/api/history/overview