Skip to content

Move stock between states

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

Moves a quantity of a variant’s stock from one state to another, for example from available to damaged, for up to 250 items in one request. from and to must differ. The request is refused with 409 when the source state does not hold enough: INSUFFICIENT_INVENTORY for available on a variant that does not allow overselling, INVENTORY_STATE_NEGATIVE for an unavailable state. reason defaults to correction. 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 moves, 1 to 250.

Array<object>
object
variant_id
required

ID of the variant.

number
>= 1 <= 9007199254740991
from
required

The state the stock leaves.

string
Allowed values: available damaged quality_control safety_stock other
to
required

The state the stock enters. It must differ from from.

string
Allowed values: available damaged quality_control safety_stock other
quantity
required

How many units to move, at least 1.

number
>= 1
reason

Why the stock is being moved. Defaults to correction.

string
default: correction
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"
}