Skip to content

Get a variant's stock history

GET
/stores/{storeRef}/inventory/variants/{variantId}/history
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/stores/example/inventory/variants/1/history?limit=50&offset=0' \
--header 'x-api-key: <x-api-key>'

Returns a page of the stock adjustments of one variant, newest first. Each entry says who made the change, why, and the order or purchase order behind it, if any. Use limit and offset to page.

Required scopes: read:inventory

variantId
required
integer

The variant ID.

storeRef
required
string

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

limit
number
default: 50 >= 1 <= 200

Maximum number of entries to return.

offset
number
0

Number of entries to skip.

Media typeapplication/json
object
data
required
Array<object>
object
reason
required

Why the stock changed.

string
Allowed values: correction count received return_restock damaged theft_or_loss promotion_or_donation other initial_stock order_reserved order_fulfilled order_released order_restocked cancelled_not_restocked migration_backfill purchase_order_ordered purchase_order_edited purchase_order_cancelled purchase_order_closed
reference
required

The order or purchase order that caused the change, or null.

object
type
required

What kind of record it is.

string
Allowed values: order purchase_order
id
required

The record’s ID.

number
label
required

A readable label, such as the order code.

string
id
required

Adjustment ID.

number
created_at
required

When it happened, as an ISO 8601 timestamp.

string
note
required

The note given with the change, or null.

string
nullable
actor
required

Who made the change.

object
type
required

Kind of actor.

string
Allowed values: staff customer api_key gateway system
id
required

Actor ID: a staff user ID or an API key ID. Null for the system.

string
nullable
name
required

Display name of the staff member or API key, or null when it cannot be resolved.

string
nullable
changes
required

The changes to this variant’s stock states.

Array<object>
object
state
required

The stock state that changed.

string
Allowed values: available committed damaged quality_control safety_stock other incoming
delta
required

How much it changed by. Negative for a decrease.

number
quantity_after
required

The quantity in that state after the change.

number
meta
required
object
total
required

Total number of items matching the request.

number
limit
required

Maximum number of items in this page.

number
offset
required

Number of items skipped before this page.

number
page
required

Current page number, starting at 1.

number
totalPages
required

Total number of pages.

number
hasNext
required

Whether a next page exists.

boolean
hasPrev
required

Whether a previous page exists.

boolean

Example

{
"data": [
{
"reason": "correction",
"reference": {
"type": "order"
},
"actor": {
"type": "staff"
},
"changes": [
{
"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"
}