Developer Docs

Inventory

Read inventory by fulfillment location and submit idempotent inventory adjustments.

GET

/api/integrations/v1/inventory

List inventory

Returns merchant inventory rows grouped by variant and fulfillment location.

POST

/api/integrations/v1/inventory/adjustments

Apply inventory adjustments

Applies merchant-scoped inventory adjustments by variant or SKU and fulfillment location.

GET

/api/integrations/v1/inventory

Read inventory

List inventory

Use this endpoint to sync available quantities or detect changed stock assignments.

Query Parameters

Supported inputs for this operation.

variant_id

uuidOptional

Filter to a specific variant.

Example: 66f1b765-1fe7-4e3a-98db-d2334f3bcb43

sku

stringOptional

Filter to a specific SKU.

Example: CAP-RED-OS

updated_after

ISO-8601 timestampOptional

Return inventory rows updated after this timestamp.

Example: 2026-03-12T18:15:00.000Z

location_id

uuidOptional

Filter to a specific fulfillment location.

Example: 77a1a4d0-93a9-4cf8-a34c-208e64b0ad4f

limit

integerOptional

Maximum number of rows returned per page.

Default: 50

cursor

stringOptional

Opaque cursor from a previous response page.

Name	Type	Required	Description
variant_id	uuid	No	Filter to a specific variant. Example: 66f1b765-1fe7-4e3a-98db-d2334f3bcb43
sku	string	No	Filter to a specific SKU. Example: CAP-RED-OS
updated_after	ISO-8601 timestamp	No	Return inventory rows updated after this timestamp. Example: 2026-03-12T18:15:00.000Z
location_id	uuid	No	Filter to a specific fulfillment location. Example: 77a1a4d0-93a9-4cf8-a34c-208e64b0ad4f
limit	integer	No	Maximum number of rows returned per page. Default: 50
cursor	string	No	Opaque cursor from a previous response page.

Headers

Supported inputs for this operation.

Authorization

Bearer tokenOptional

Preferred API key header.

X-API-Key

stringOptional

Fallback API key header.

Name	Type	Required	Description
Authorization	Bearer token	No	Preferred API key header.
X-API-Key	string	No	Fallback API key header.

Examples

Switch between the sample request and example responses for this endpoint.

Sample cURL

curl -X GET "https://merchants.rarely.co/api/integrations/v1/inventory" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST

/api/integrations/v1/inventory/adjustments

Write inventory

Apply inventory adjustments

Provide one or more adjustment rows. If an idempotency key is reused with the same payload, the stored response is replayed.

Headers

Supported inputs for this operation.

Authorization

Bearer tokenOptional

Preferred API key header.

X-API-Key

stringOptional

Fallback API key header.

Idempotency-Key

stringOptional

Recommended for write safety. The same key with the same payload replays the stored response.

Example: inventory-adjustment-001

Name	Type	Required	Description
Authorization	Bearer token	No	Preferred API key header.
X-API-Key	string	No	Fallback API key header.
Idempotency-Key	string	No	Recommended for write safety. The same key with the same payload replays the stored response. Example: inventory-adjustment-001

Request Body

JSON payload fields accepted by this endpoint.

adjustments

arrayRequired

List of inventory adjustment rows.

adjustments[].variant_id

uuidOptional

Variant to adjust. Required if SKU is not provided.

adjustments[].sku

stringOptional

SKU to resolve when variant_id is omitted.

adjustments[].fulfillment_location_id

uuidRequired

Fulfillment location to adjust.

adjustments[].adjustment

integerRequired

Signed quantity delta to apply.

adjustments[].reason

stringOptional

Operational reason string for the adjustment.

Field	Type	Required	Description
adjustments	array	Yes	List of inventory adjustment rows.
adjustments[].variant_id	uuid	No	Variant to adjust. Required if SKU is not provided.
adjustments[].sku	string	No	SKU to resolve when variant_id is omitted.
adjustments[].fulfillment_location_id	uuid	Yes	Fulfillment location to adjust.
adjustments[].adjustment	integer	Yes	Signed quantity delta to apply.
adjustments[].reason	string	No	Operational reason string for the adjustment.

Examples

Switch between the sample request and example responses for this endpoint.

Sample cURL

curl -X POST "https://merchants.rarely.co/api/integrations/v1/inventory/adjustments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "adjustments": [
    {
      "variant_id": "66f1b765-1fe7-4e3a-98db-d2334f3bcb43",
      "fulfillment_location_id": "77a1a4d0-93a9-4cf8-a34c-208e64b0ad4f",
      "adjustment": 5,
      "reason": "cycle count reconciliation"
    }
  ]
}'

Live PlaygroundClient memory only

Test live requests against your merchant integration API.

The docs app proxies requests server-side to the merchant API. Your API key stays in local browser memory for the current docs session and is never stored by this UI.

Operation

Auth mode

API key

Query: variant_id

Query: sku

Query: updated_after

Query: location_id

Query: limit

Query: cursor

Resolved request

https://merchants.rarely.co/api/integrations/v1/inventory

Live Output

Switch between the generated request and the most recent live response.

Generated cURL

curl -X GET "https://merchants.rarely.co/api/integrations/v1/inventory" \
  -H "Authorization: Bearer YOUR_API_KEY"

Inventory

Search developer docs