Skip to content

Set a product's absolute stock level at one outlet

Open in ClaudeOpen in ChatGPTView as Markdown
PUT
/products/{id}/inventory/{outlet_id}

Loop-safe: the delta is computed server-side from the current level under a row lock, so sending the same on_hand twice writes nothing the second time (changed: false).

  • A supplied reason_id must match the computed direction, or leave it out to use the system “Stock set via API” reason.

  • Idempotency-Key is optional here: the write is already idempotent by construction.

  • 422 REASON_DIRECTION_MISMATCH: the supplied reason_id does not match the computed direction.

  • 422 REASON_NOT_ALLOWED: the supplied reason_id is a system reason or is turned off. A reason must be enabled and must not be a system reason.

  • 422 OUTLET_DELETED: the outlet has been deleted.

unit_cost (integer cents, optional) becomes the average cost for the outlet, whether stock goes up, down or stays the same. Leave it out to keep the current average, or the supply price when there is no average yet.

Requires scope: inventory:write

Authorizations

Section titled “Authorizations”

Request Body

Section titled “Request Body”
Media typeapplication/json
object
note
Any of:
string
<= 2000 characters
on_hand
required
number
reason_id
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
unit_cost
Any of:
integer
<= 900719925474
Examplegenerated
{
  "note": "example",
  "on_hand": 1,
  "reason_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "unit_cost": 1
}

Responses

Section titled “Responses”

200

Section titled “200”

Set a product’s absolute stock level at one outlet

Media typeapplication/json
object
data
required
object
adjustment_id
required
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
changed
required
boolean
delta
required
number
movement_id
required
Any of:
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
on_hand
required
number
previous
required
number
Examplegenerated
{
  "data": {
    "adjustment_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "changed": true,
    "delta": 1,
    "movement_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
    "on_hand": 1,
    "previous": 1
  }
}

default

Section titled “default”

An error response.

Media typeapplication/json
object
error
required
object
code
required

A machine-readable error code, e.g. VALIDATION_FAILED.

string
Allowed values: UNAUTHORIZED PLAN_REQUIRED INSUFFICIENT_SCOPE NOT_FOUND VALIDATION_FAILED CONFLICT STALE_VERSION RATE_LIMITED IDEMPOTENCY_KEY_REUSED IDEMPOTENCY_IN_PROGRESS IMAGE_FETCH_FAILED UNPROCESSABLE INTERNAL RETAILER_CANCELLED RETAILER_SUSPENDED RETAILER_NOT_FOUND TRIAL_DECISION_REQUIRED PLAN_USERS_EXCEEDED RETAILER_PAUSED PRODUCT_LIMIT_REACHED NOT_STOCK_TRACKED REASON_DIRECTION_MISMATCH REASON_NOT_ALLOWED INSUFFICIENT_STOCK OUTLET_DELETED
fields
Array<object>
object
field
required
string
message
required
string
message
required

A plain-English sentence describing what went wrong.

string
Example
{
  "error": {
    "code": "UNAUTHORIZED"
  }
}