Skip to content

Adjust stock quantities

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

Changes available or one of the unavailable states (damaged, quality_control, safety_stock, other) by a positive or negative delta, for up to 250 items in one request. available may be adjusted below zero, but an unavailable state may not: that request is refused with 409 INVENTORY_STATE_NEGATIVE. 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 changes, 1 to 250. A variant may repeat with different states.

Array<object>
object
variant_id
required

ID of the variant.

number
>= 1 <= 9007199254740991
state
required

The state to change.

string
Allowed values: available damaged quality_control safety_stock other
delta
required

Never zero.

number
reason
required

Why the stock is being adjusted.

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
replayed
required

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

boolean

Example

{
"applied": [
{
"inventory_policy": "deny"
}
]
}

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"
}