Skip to content

Set stock quantities

POST
/stores/{storeRef}/inventory/levels/set
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/stores/example/inventory/levels/set \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "note": "example", "idempotency_key": "example", "items": [ { "variant_id": 1, "state": "available", "quantity": 1, "expected_quantity": 1 } ], "reason": "correction" }'

Sets available or on_hand to an exact quantity for up to 250 variants in one request, each variant at most once. Give expected_quantity on an item to refuse the write when the stock has changed since you read it; if any item is stale the request answers 409 INVENTORY_QUANTITY_STALE, but the items that were not stale are still written: their levels are in details.applied and the stale items are in details.stale. Do not retry the whole request blindly; retry only the stale items. The change is recorded in each variant’s history with the reason. Sending the same idempotency_key again writes nothing and answers with replayed true.

Required scopes: write:inventory

storeRef
required
string

The store’s ref, as returned by GET /stores.

Media typeapplication/json
object
note

A note recorded with the change in the variants’ history.

string
nullable <= 500 characters
idempotency_key

Repeating a key makes the request a no-op.

string
nullable <= 100 characters
items
required

The variants to set, 1 to 250, each at most once.

Array<object>
object
variant_id
required

ID of the variant.

number
>= 1 <= 9007199254740991
state
required

Which quantity to set: available, or on_hand for the total held.

string
Allowed values: available on_hand
quantity
required

The new quantity, never negative.

number
expected_quantity

The quantity the caller last saw.

number
nullable
reason
required

Why the stock is being set.

string
Allowed values: correction count received return_restock damaged theft_or_loss promotion_or_donation other
Media typeapplication/json
object
applied
required

The levels that were written, as they are now.

Array<object>
object
inventory_policy
required

What happens when stock runs out: deny stops sales, continue keeps selling.

string
Allowed values: deny continue
variant_id
required

Variant ID.

number
product_id
required

ID of the product the variant belongs to.

number
product_name
required

Product name.

string
product_image
required

Product image URL, or null.

string
nullable
variant_title
required

The variant’s option values joined with /, or null for a product without options.

string
nullable
sku
required

Stock keeping unit, or null.

string
nullable
location_id
required

ID of the location that holds the stock.

number
track_inventory
required

Whether stock is tracked for the variant.

boolean
available
required

Units that can be sold now.

number
committed
required

Units reserved by orders that are not yet fulfilled.

number
damaged
required

Units set aside as damaged.

number
quality_control
required

Units set aside for quality control.

number
safety_stock
required

Units held back as safety stock.

number
other
required

Units set aside for another reason.

number
unavailable
required

Total of damaged, quality control, safety stock and other.

number
on_hand
required

Units physically held: available, committed and unavailable together.

number
incoming
required

Units expected from open purchase orders.

number
updated_at
required

When the level last changed, as an ISO 8601 timestamp.

string
stale
required

Always empty here. A request with a stale item is refused with 409, and the stale items are in the error’s details.

Array<object>
object
state
required

The quantity that was being set.

string
Allowed values: available on_hand
variant_id
required

Variant ID.

number
expected_quantity
required

The quantity the caller expected, from expected_quantity.

number
current_quantity
required

The quantity the variant actually holds now.

number
replayed
required

True when the idempotency_key was used before: nothing was written and applied is empty.

boolean

Example

{
"applied": [
{
"inventory_policy": "deny"
}
],
"stale": [
{
"state": "available"
}
]
}

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The resource does not exist in this store.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The request conflicts with the resource’s current state.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}