Inventory levels API

GET `/api/integrations/v2/{connection_id}/inventory-levels`

The workspace’s stock levels per unit and location, keyset-paged on (updated_at, id).

Parameters

Name	In	Type	Required	Description
`connection_id`	path	string (uuid)	yes	Your custom integration’s id; the connection whose secret signs the request.
`updated_since`	query	string (date-time), nullable	no	Only rows changed at or after this instant (inclusive).
`cursor`	query	string, nullable	no	The `next_cursor` of the previous page, as given.
`limit`	query	integer	no	Page size; at most 250 rows are answered whatever is asked. Default 50.

Headers

Header	Required	Description
`X-Yedran-Timestamp`	yes	Unix seconds; within five minutes of the server’s clock.
`X-Yedran-Signature`	yes	Lowercase hex HMAC-SHA256, keyed with the integration’s API secret, over METHOD\npath\ntimestamp\nsha256_hex(body).
`Yedran-Version`	no	Optional: the contract version, `2026-10` today; absent is `2026-10`. Any other value is 400 `unsupported_version`. Every answer echoes the version served.

Response 200

Schema InventoryLevelPageV2.

Field	Type	Required	Description
`data`	array of InventoryLevelV2	yes
`next_cursor`	string, nullable	yes

Example

curl -X GET "https://app.yedran.com/api/integrations/v2/{connection_id}/inventory-levels?limit=1" \
  -H "X-Yedran-Timestamp: $TIMESTAMP" \
  -H "X-Yedran-Signature: $SIGNATURE" \
  -H "Yedran-Version: 2026-10"

Response 200:

{
  "data": [
    {
      "product_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
      "sku": "string",
      "location_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
      "location_external_id": "string",
      "on_hand": "string",
      "reserved": "string",
      "available": "string",
      "version": 1,
      "source": "yedran",
      "observed_at": "2026-10-02T09:00:00Z",
      "updated_at": "2026-10-02T09:00:00Z"
    }
  ],
  "next_cursor": "string"
}

Errors

Code	Meaning
400	Bad Request
401	Unauthorized
422	Unprocessable Entity

PUT `/api/integrations/v2/{connection_id}/inventory-levels/by-sku/{sku}`

Set the reading of a unit whose stock you master, at one of your locations (K4).

Requires inventory enabled inbound (403 not_enabled) and the unit tracked with this integration as its stock master (409 not_stock_master). compare_quantity makes it compare-and-set (409 quantity_mismatch).

Parameters

Name	In	Type	Required	Description
`connection_id`	path	string (uuid)	yes	Your custom integration’s id; the connection whose secret signs the request.
`sku`	path	string	yes	Our sku for the unit (one variant).

Headers

Header	Required	Description
`X-Yedran-Timestamp`	yes	Unix seconds; within five minutes of the server’s clock.
`X-Yedran-Signature`	yes	Lowercase hex HMAC-SHA256, keyed with the integration’s API secret, over METHOD\npath\ntimestamp\nsha256_hex(body).
`Yedran-Version`	no	Optional: the contract version, `2026-10` today; absent is `2026-10`. Any other value is 400 `unsupported_version`. Every answer echoes the version served.
`Idempotency-Key`	yes	Required on every write: a unique key per logical request, kept 24 hours.

Request body

Schema InventoryLevelWriteV2.

Field	Type	Required
`available`	number or string	yes
`on_hand`	number or string, nullable	no
`compare_quantity`	number or string, nullable	no
`location_external_id`	string, nullable	no
`location_name`	string, nullable	no
`observed_at`	string (date-time), nullable	no

Response 200

Schema InventoryLevelV2.

Field	Type	Required
`product_id`	string (uuid)	yes
`sku`	string	yes
`location_id`	string (uuid)	yes
`location_external_id`	string, nullable	yes
`on_hand`	string	yes
`reserved`	string	yes
`available`	string	yes
`version`	integer	yes
`source`	one of `yedran`, `integration`	yes
`observed_at`	string (date-time), nullable	yes
`updated_at`	string (date-time)	yes

Example

curl -X PUT "https://app.yedran.com/api/integrations/v2/{connection_id}/inventory-levels/by-sku/string" \
  -H "X-Yedran-Timestamp: $TIMESTAMP" \
  -H "X-Yedran-Signature: $SIGNATURE" \
  -H "Yedran-Version: 2026-10" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"available": 1}'

Response 200:

{
  "product_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "sku": "string",
  "location_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "location_external_id": "string",
  "on_hand": "string",
  "reserved": "string",
  "available": "string",
  "version": 1,
  "source": "yedran",
  "observed_at": "2026-10-02T09:00:00Z",
  "updated_at": "2026-10-02T09:00:00Z"
}

Errors

Code	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
422	Unprocessable Entity

PUT `/api/integrations/v2/{connection_id}/inventory-levels/by-external-id/{external_id}`

As by-sku, naming the unit by the external id you bound it with.

Parameters

Name	In	Type	Required	Description
`connection_id`	path	string (uuid)	yes	Your custom integration’s id; the connection whose secret signs the request.
`external_id`	path	string	yes	Your id for the unit, as bound by a product upsert.

Headers

Header	Required	Description
`X-Yedran-Timestamp`	yes	Unix seconds; within five minutes of the server’s clock.
`X-Yedran-Signature`	yes	Lowercase hex HMAC-SHA256, keyed with the integration’s API secret, over METHOD\npath\ntimestamp\nsha256_hex(body).
`Yedran-Version`	no	Optional: the contract version, `2026-10` today; absent is `2026-10`. Any other value is 400 `unsupported_version`. Every answer echoes the version served.
`Idempotency-Key`	yes	Required on every write: a unique key per logical request, kept 24 hours.

Request body

Schema InventoryLevelWriteV2.

Field	Type	Required
`available`	number or string	yes
`on_hand`	number or string, nullable	no
`compare_quantity`	number or string, nullable	no
`location_external_id`	string, nullable	no
`location_name`	string, nullable	no
`observed_at`	string (date-time), nullable	no

Response 200

Schema InventoryLevelV2.

Field	Type	Required
`product_id`	string (uuid)	yes
`sku`	string	yes
`location_id`	string (uuid)	yes
`location_external_id`	string, nullable	yes
`on_hand`	string	yes
`reserved`	string	yes
`available`	string	yes
`version`	integer	yes
`source`	one of `yedran`, `integration`	yes
`observed_at`	string (date-time), nullable	yes
`updated_at`	string (date-time)	yes

Example

curl -X PUT "https://app.yedran.com/api/integrations/v2/{connection_id}/inventory-levels/by-external-id/string" \
  -H "X-Yedran-Timestamp: $TIMESTAMP" \
  -H "X-Yedran-Signature: $SIGNATURE" \
  -H "Yedran-Version: 2026-10" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"available": 1}'

Response 200:

{
  "product_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "sku": "string",
  "location_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "location_external_id": "string",
  "on_hand": "string",
  "reserved": "string",
  "available": "string",
  "version": 1,
  "source": "yedran",
  "observed_at": "2026-10-02T09:00:00Z",
  "updated_at": "2026-10-02T09:00:00Z"
}

Errors

Code	Meaning
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
422	Unprocessable Entity

Schemas

InventoryLevelPageV2

A page of levels, (updated_at, id) ascending; next_cursor null on the last.

Field	Type	Required	Description
`data`	array of InventoryLevelV2	yes
`next_cursor`	string, nullable	yes

InventoryLevelWriteV2

An integration’s reading of one unit at one location (K4).

available is required; on_hand, when sent, is at least available (the rest is held). compare_quantity is compare-and-set: the write is refused 409 quantity_mismatch unless the stored available equals it. location_external_id names your location (bound on first use); omitted, the workspace’s default location. observed_at is when you read it; omitted, now.

Field	Type	Required
`available`	number or string	yes
`on_hand`	number or string, nullable	no
`compare_quantity`	number or string, nullable	no
`location_external_id`	string, nullable	no
`location_name`	string, nullable	no
`observed_at`	string (date-time), nullable	no

InventoryLevelV2

One unit’s level at one location, as the integration API shows it.

Field	Type	Required
`product_id`	string (uuid)	yes
`sku`	string	yes
`location_id`	string (uuid)	yes
`location_external_id`	string, nullable	yes
`on_hand`	string	yes
`reserved`	string	yes
`available`	string	yes
`version`	integer	yes
`source`	one of `yedran`, `integration`	yes
`observed_at`	string (date-time), nullable	yes
`updated_at`	string (date-time)	yes

Inventory levels API

Inventory levels API

GET /api/integrations/v2/{connection_id}/inventory-levels

Parameters

Headers

Response 200

Example

Errors

PUT /api/integrations/v2/{connection_id}/inventory-levels/by-sku/{sku}

Parameters

Headers

Request body

Response 200

Example

Errors

PUT /api/integrations/v2/{connection_id}/inventory-levels/by-external-id/{external_id}

Parameters

Headers

Request body

Response 200

Example

Errors

Schemas

InventoryLevelPageV2

InventoryLevelWriteV2

InventoryLevelV2

GET `/api/integrations/v2/{connection_id}/inventory-levels`

PUT `/api/integrations/v2/{connection_id}/inventory-levels/by-sku/{sku}`

PUT `/api/integrations/v2/{connection_id}/inventory-levels/by-external-id/{external_id}`