CHcheckout
Inventory

Submit a batch ingestion

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.

post/inventory/ingestions

Request

Headers

Cko-Idempotency-Keystring

An optional idempotency key for safely retrying payment requests

Request body

mode'upsert'

The update semantics for the batch. Only upsert is available in this version.

Example request

{
  "mode": "upsert",
  "items": [
    {
      "stock": {
        "on_hand": 25,
        "safety_stock": 2,
        "reason": "stock take 2026-07"
      },
      "variant_id": "var_123",
      "product": {
        "title": "Classic leather belt, brown",
        "description": "A full-grain leather belt with a brushed nickel buckle.",
        "product_url": "https://merchant.example.com/products/classic-leather-belt-brown",
        "image_url": "https://merchant.example.com/images/belt-brown-main.jpg",
        "additional_image_urls": [
          "https://merchant.example.com/images/belt-brown-alt1.jpg"
        ],
        "video_url": "https://merchant.example.com/videos/belt-brown.mp4",
        "model_3d_url": "https://merchant.example.com/models/belt-brown.glb",
        "sku": "BELT-BRN-001",
        "gtin": "00012345678905",
        "mpn": "MPN-4471",
        "brand": "Acme Leathercraft",
        "category": "Apparel & Accessories > Belts",
        "price": {
          "amount": 1999,
          "currency": "USD"
        },
        "sale_price": {
          "amount": 1999,
          "currency": "USD"
        },
        "sale_price_starts_at": "2026-08-01T00:00:00.0000000+00:00",
        "sale_price_ends_at": "2026-08-31T23:59:59.0000000+00:00",
        "group_id": "grp_belt_classic",
        "group_title": "Classic leather belt",
        "color": "Brown",
        "size": "M",
        "size_system": "US",
        "gender": "unisex",
        "condition": "new",
        "material": "Full-grain leather",
        "age_group": "adult",
        "length": 110,
        "width": 3.5,
        "height": 0.5,
        "dimension_unit": "cm",
        "weight": 0.2,
        "weight_unit": "kg",
        "expiration_date": "2027-01-01T00:00:00.0000000+00:00",
        "harmonized_system_code": "4203.30",
        "country_of_origin": "IT",
        "seller_name": "Acme Leathercraft Ltd",
        "seller_url": "https://acme-leathercraft.example.com",
        "seller_privacy_policy": "https://acme-leathercraft.example.com/privacy",
        "seller_tos": "https://acme-leathercraft.example.com/terms"
      }
    }
  ]
}

Response

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

idstring

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.

upload_urlstring

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_onstring date-time

The date and time the job was created.

modified_onstring date-time

The date and time the job was last updated.

Example response

{
  "id": "ing_01hzy8q2m4n6p8r0s2t4v6w8x0",
  "state": "accepted",
  "mode": "upsert",
  "counts": {
    "received": 500,
    "accepted": 498,
    "rejected": 2
  },
  "failure_reason": {
    "code": "file_unreadable",
    "message": "The uploaded file could not be read as CSV."
  },
  "upload_url": "https://inventory-ingestions.s3.eu-west-1.amazonaws.com/ingestions/mer_1/ing_.../payload.csv?X-Amz-Signature=...",
  "created_on": "2026-09-24T15:04:05.0000000+00:00",
  "modified_on": "2026-09-24T15:04:11.0000000+00:00",
  "_links": {
    "self": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": [
        "GET"
      ],
      "types": [
        "application/json"
      ]
    },
    "results": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": [
        "GET"
      ],
      "types": [
        "application/json"
      ]
    },
    "start": {
      "href": "https://api.checkout.com/inventory/var_123",
      "actions": [
        "GET"
      ],
      "types": [
        "application/json"
      ]
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.