---
title: "Submit a batch ingestion"
method: POST
path: "/inventory/ingestions"
tags: ["Inventory"]
---

# Submit a batch ingestion

`POST /inventory/ingestions`

## Request

- Base URL: `https://{prefix}.api.sandbox.checkout.com`
- URL: `https://{prefix}.api.sandbox.checkout.com/inventory/ingestions`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `string` scopes: `agentic:inventory`
- TypeScript: <https://skmtc.dev/checkout/apis/checkout-com-api-reference/docs/inventory/ingestions/post.ts> (a function with typed inputs; its response is checked against the schema)

Submits a batch of up to 500 items, covering stock, product knowledge, or both, for
asynchronous processing, and returns `202 Accepted` with an ingestion job to poll. Processing is non-atomic: Good items apply even if some are rejected, and the per-item outcome is available at
`/inventory/ingestions/{id}/results`.

Ingestion sets the baseline stock and never overrides an active reservation, so it can never cause an oversell.

Include a Cko-Idempotency-Key header to make a retried submit safe: a repeat with the same key returns the original job instead of creating a duplicate batch.

Requires the `agentic:inventory` scope.

## Headers

- `Cko-Idempotency-Key` string

## Request body

- InventoryIngestionRequest: <span style="font-size: 12px; font-weight: 500; color: rgb(0, 0, 0); background-color: rgb(255, 176, 97); border-radius: 4px; padding: 2px 6px" >Beta</span><p></p> The body of a JSON batch submit. Processing is asynchronous and non-atomic: good items apply even if some are rejected.
  - `mode` 'upsert': The update semantics for the batch. Only `upsert` is available in this version.
  - `items` InventoryIngestionItem[], required: The list of items to apply. Up to 500 items per batch.
    - union: <span style="font-size: 12px; font-weight: 500; color: rgb(0, 0, 0); background-color: rgb(255, 176, 97); border-radius: 4px; padding: 2px 6px" >Beta</span><p></p> One item in a JSON batch. Provide: - `stock` to set stock - `product` to set product knowledge, or - both. At least one of the two must be present.
      - object
        - `stock` InventorySetLevelsRequest, required: <span style="font-size: 12px; font-weight: 500; color: rgb(0, 0, 0); background-color: rgb(255, 176, 97); border-radius: 4px; padding: 2px 6px" >Beta</span><p></p> The request body for setting absolute stock levels on a variant.
          - `on_hand` integer, required: The absolute physical stock to set for the variant.
          - `safety_stock` integer: The buffer quantity to withhold from sale. Defaults to `0` when the item is created and is left unchanged on update if omitted.
          - `reason` string: An optional free-text reason recorded in the ledger. Must not contain personal data.
        - `variant_id` string, required: The merchant's variant identifier, unique within the merchant.
        - `product` InventorySetProductRequest: <span style="font-size: 12px; font-weight: 500; color: rgb(0, 0, 0); background-color: rgb(255, 176, 97); border-radius: 4px; padding: 2px 6px" >Beta</span><p></p> The request body for setting the product knowledge for a variant. The call is an upsert.
          - `title` string, required: The product's display title.
          - `description` string, required: The product's display description.
          - `product_url` string, required: The canonical URL for the product page.
          - `image_url` string, required: The URL of the primary product image.
          - `additional_image_urls` string[]: Additional product image URLs, beyond `image_url`.
          - `video_url` string: The URL of a product video.
          - `model_3d_url` string: The URL of a 3D model of the product.
          - `sku` string: The merchant's stock-keeping unit for the product.
          - `gtin` string: The product's Global Trade Item Number (UPC, EAN, ISBN, or JAN).
          - `mpn` string: The product's Manufacturer Part Number.
          - `brand` string: The product's brand name.
          - `category` string: The merchant's category for the product.
          - `price` InventoryMoney: A monetary amount in the currency's minor units.
            - `amount` integer, required: The amount in the <a href="https://www.checkout.com/docs/resources/calculating-the-amount" target="_blank">minor currency unit</a>.
            - `currency` string, required: The three-letter <a href="https://www.checkout.com/docs/resources/codes/currency-codes" target="_blank">ISO 4217 currency code</a>.
          - `sale_price` InventoryMoney: A monetary amount in the currency's minor units.
            - `amount` integer, required: The amount in the <a href="https://www.checkout.com/docs/resources/calculating-the-amount" target="_blank">minor currency unit</a>.
            - `currency` string, required: The three-letter <a href="https://www.checkout.com/docs/resources/codes/currency-codes" target="_blank">ISO 4217 currency code</a>.
          - `sale_price_starts_at` string, date-time: The date and time from which `sale_price` applies. Paired with `sale_price`.
          - `sale_price_ends_at` string, date-time: The date and time after which `sale_price` no longer applies. Paired with `sale_price`.
          - `group_id` string: The identifier shared by all variants of the same product (for example, the same belt in different sizes). When set, `color` and `size` are both required.
          - `group_title` string: A display title for the variant group.
          - `color` string: The variant's color. Required when `group_id` is set.
          - `size` string: The variant's size. Required when `group_id` is set.
          - `size_system` string: The sizing system that `size` is expressed in.
          - `gender` string: The target gender for the product.
          - `condition` 'new' | 'used' | 'refurbished': The product's condition, as an exact lowercase match of one of the enum values. Defaults to `new` when omitted.
          - `material` string: The product's primary material.
          - `age_group` string: The target age group for the product.
          - `length` number: The product's length. `length`, `width`, `height` and `dimension_unit` must be provided together, or not at all.
          - `width` number: The product's width. `length`, `width`, `height` and `dimension_unit` must be provided together, or not at all.
          - `height` number: The product's height. `length`, `width`, `height` and `dimension_unit` must be provided together, or not at all.
          - `dimension_unit` string: The unit that `length`, `width` and `height` are expressed in. Required when any of `length`, `width` or `height` is set.
          - `weight` number: The product's weight. Must be provided together with `weight_unit`, or not at all.
          - `weight_unit` string: The unit that `weight` is expressed in. Required when `weight` is set.
          - `expiration_date` string, date-time: The date and time after which the product should no longer be offered.
          - `harmonized_system_code` string: The product's Harmonized System (HS) code, for customs purposes.
          - `country_of_origin` string: The two-letter ISO 3166-1 alpha-2 country of origin.
          - `seller_name` string: The name of the seller of record, when different from the merchant.
          - `seller_url` string: The URL of the seller of record.
          - `seller_privacy_policy` string: The URL of the seller's privacy policy.
          - `seller_tos` string: The URL of the seller's terms of service.
      - object
        - `product` InventorySetProductRequest, required: <span style="font-size: 12px; font-weight: 500; color: rgb(0, 0, 0); background-color: rgb(255, 176, 97); border-radius: 4px; padding: 2px 6px" >Beta</span><p></p> The request body for setting the product knowledge for a variant. The call is an upsert.
          - `title` string, required: The product's display title.
          - `description` string, required: The product's display description.
          - `product_url` string, required: The canonical URL for the product page.
          - `image_url` string, required: The URL of the primary product image.
          - `additional_image_urls` string[]: Additional product image URLs, beyond `image_url`.
          - `video_url` string: The URL of a product video.
          - `model_3d_url` string: The URL of a 3D model of the product.
          - `sku` string: The merchant's stock-keeping unit for the product.
          - `gtin` string: The product's Global Trade Item Number (UPC, EAN, ISBN, or JAN).
          - `mpn` string: The product's Manufacturer Part Number.
          - `brand` string: The product's brand name.
          - `category` string: The merchant's category for the product.
          - `price` InventoryMoney: A monetary amount in the currency's minor units.
            - `amount` integer, required: The amount in the <a href="https://www.checkout.com/docs/resources/calculating-the-amount" target="_blank">minor currency unit</a>.
            - `currency` string, required: The three-letter <a href="https://www.checkout.com/docs/resources/codes/currency-codes" target="_blank">ISO 4217 currency code</a>.
          - `sale_price` InventoryMoney: A monetary amount in the currency's minor units.
            - `amount` integer, required: The amount in the <a href="https://www.checkout.com/docs/resources/calculating-the-amount" target="_blank">minor currency unit</a>.
            - `currency` string, required: The three-letter <a href="https://www.checkout.com/docs/resources/codes/currency-codes" target="_blank">ISO 4217 currency code</a>.
          - `sale_price_starts_at` string, date-time: The date and time from which `sale_price` applies. Paired with `sale_price`.
          - `sale_price_ends_at` string, date-time: The date and time after which `sale_price` no longer applies. Paired with `sale_price`.
          - `group_id` string: The identifier shared by all variants of the same product (for example, the same belt in different sizes). When set, `color` and `size` are both required.
          - `group_title` string: A display title for the variant group.
          - `color` string: The variant's color. Required when `group_id` is set.
          - `size` string: The variant's size. Required when `group_id` is set.
          - `size_system` string: The sizing system that `size` is expressed in.
          - `gender` string: The target gender for the product.
          - `condition` 'new' | 'used' | 'refurbished': The product's condition, as an exact lowercase match of one of the enum values. Defaults to `new` when omitted.
          - `material` string: The product's primary material.
          - `age_group` string: The target age group for the product.
          - `length` number: The product's length. `length`, `width`, `height` and `dimension_unit` must be provided together, or not at all.
          - `width` number: The product's width. `length`, `width`, `height` and `dimension_unit` must be provided together, or not at all.
          - `height` number: The product's height. `length`, `width`, `height` and `dimension_unit` must be provided together, or not at all.
          - `dimension_unit` string: The unit that `length`, `width` and `height` are expressed in. Required when any of `length`, `width` or `height` is set.
          - `weight` number: The product's weight. Must be provided together with `weight_unit`, or not at all.
          - `weight_unit` string: The unit that `weight` is expressed in. Required when `weight` is set.
          - `expiration_date` string, date-time: The date and time after which the product should no longer be offered.
          - `harmonized_system_code` string: The product's Harmonized System (HS) code, for customs purposes.
          - `country_of_origin` string: The two-letter ISO 3166-1 alpha-2 country of origin.
          - `seller_name` string: The name of the seller of record, when different from the merchant.
          - `seller_url` string: The URL of the seller of record.
          - `seller_privacy_policy` string: The URL of the seller's privacy policy.
          - `seller_tos` string: The URL of the seller's terms of service.
        - `variant_id` string, required: The merchant's variant identifier, unique within the merchant.
        - `stock` InventorySetLevelsRequest: <span style="font-size: 12px; font-weight: 500; color: rgb(0, 0, 0); background-color: rgb(255, 176, 97); border-radius: 4px; padding: 2px 6px" >Beta</span><p></p> The request body for setting absolute stock levels on a variant.
          - `on_hand` integer, required: The absolute physical stock to set for the variant.
          - `safety_stock` integer: The buffer quantity to withhold from sale. Defaults to `0` when the item is created and is left unchanged on update if omitted.
          - `reason` string: An optional free-text reason recorded in the ledger. Must not contain personal data.

## Response `202`

The batch was accepted for processing, or the original job on an idempotent replay.

- InventoryIngestion: <span style="font-size: 12px; font-weight: 500; color: rgb(0, 0, 0); background-color: rgb(255, 176, 97); border-radius: 4px; padding: 2px 6px" >Beta</span><p></p> An asynchronous batch-ingestion job and its current state. Poll it until `state` is terminal, then read the per-item report at `/inventory/ingestions/{id}/results`.
  - `id` string: The ingestion identifier, in the `ing_{base32-encoded GUID}` format.
  - `state` 'awaiting_upload' | 'accepted' | 'processing' | 'completed' | 'completed_with_errors' | 'failed': The current state of the job. `awaiting_upload` is only used by the CSV flow, between requesting an upload slot and starting processing. `completed`, `completed_with_errors` and `failed` are terminal.
  - `mode` 'upsert': The update semantics for the batch. Only `upsert` is available in this version.
  - `counts` InventoryIngestionCounts: <span style="font-size: 12px; font-weight: 500; color: rgb(0, 0, 0); background-color: rgb(255, 176, 97); border-radius: 4px; padding: 2px 6px" >Beta</span><p></p> The running item tally for an ingestion job. `pending` reaches `0` when the job is terminal.
    - `received` integer: The number of items received in the batch or parsed from the file.
    - `accepted` integer: The number of items applied successfully so far.
    - `rejected` integer: The number of items rejected so far, each recorded in the results report.
    - `pending` integer: The number of items still to be processed. `0` once the job is terminal.
  - `failure_reason` InventoryIngestionFailureReason: <span style="font-size: 12px; font-weight: 500; color: rgb(0, 0, 0); background-color: rgb(255, 176, 97); border-radius: 4px; padding: 2px 6px" >Beta</span><p></p> Why an ingestion job failed as a whole. Present only when `state` is `failed`. A merchant-owned code (for example `file_unreadable`) can be acted on directly; a Checkout-owned code (`internal_error`, `processing_timeout`) is alerted on our side and a re-submit is idempotency-safe.
    - `code` string: A machine-readable failure code.
    - `message` string: A human-readable explanation of the failure.
  - `upload_url` string: A short-lived, `PUT`-only presigned URL to upload the CSV file to. Present only on the response to a CSV upload-slot request.
  - `created_on` string, date-time: The date and time the job was created.
  - `modified_on` string, date-time: The date and time the job was last updated.
  - `_links` object: Links to the operations valid for the job's current state. An `awaiting_upload` job also exposes `start`.
    - `self` InventoryHalLink: A HAL link describing a related operation on the resource.
      - `href` string: Absolute URI of the linked resource.
      - `actions` string[]: The HTTP methods supported on the linked resource.
      - `types` string[]: The media types supported on the linked resource.
    - `results` InventoryHalLink: A HAL link describing a related operation on the resource.
      - `href` string: Absolute URI of the linked resource.
      - `actions` string[]: The HTTP methods supported on the linked resource.
      - `types` string[]: The media types supported on the linked resource.
    - `start` InventoryHalLink: A HAL link describing a related operation on the resource.
      - `href` string: Absolute URI of the linked resource.
      - `actions` string[]: The HTTP methods supported on the linked resource.
      - `types` string[]: The media types supported on the linked resource.

## Other responses

- `401`: Missing or invalid token.
- `403`: The token does not carry the `agentic:inventory` scope.
- `409`: The `Cko-Idempotency-Key` was reused with a different request body (`idempotency_key_reuse`).
- `413`: The batch exceeds the maximum number of items (`payload_too_large`). Nothing is applied.
- `422`: Request validation failed.
- `429`: Rate limit exceeded, or the merchant already has the maximum number of ingestion jobs in flight (`too_many_concurrent_ingestions`).

---

[API](https://skmtc.dev/checkout/apis/checkout-com-api-reference.md) - [All operations](https://skmtc.dev/checkout/apis/checkout-com-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/checkout/apis/checkout-com-api-reference/revisions/0f1abdb1c3e9?raw)