Stock & transfers

Returns the paging caps, sort columns, item types, the user reason enum accepted by adjustments, the adjustment batch cap (adjustments.max_batch_size, the per-request row cap shared by every stock write), the Idempotency-Key length limit, and the movement retention window enforced by the services.

Returns one row per (item, location) across directly tracked simple products and variants plus inventory groups. quantity is physical on hand. reserved is all held stock; checkout_held is its short unpaid-checkout subset, order_committed is its placed-order subset, and other_held covers active transfers and other operational holds. available = quantity - reserved. Every visible active location is projected for every inventory group; a missing stored level reads as zero and the first set, adjustment, or threshold write creates it atomically. App tokens see merchant-managed locations and their own app-managed locations, never another app's locations. Filter by location, item type, SKU search, or low-stock only. Query validation is strict: invalid sort or filter values return coded 400s, never silent defaults.

Pages follow the sort, then item type and IDs. While has_next is true, pass next_cursor as cursor to read the next page; page numbers reach only the first 10,000 rows. total is exact up to 10,000 rows; above that it is an estimate and total_estimated is true.

Returns the append-only ledger every physical stock change writes — admin edits, imports, scanner sessions, transfers, order fulfillment, and your own adjustments — newest first. An app-token write records App: <app name> in user_name; opaque app ids are never shown as merchant-facing actor names. A valid app token always resolves its authoritative app name, and a request with incomplete app identity is rejected. A merchant-created Store API token records its creator's merchant email. System rows without a human or app actor return an empty actor. reference_type and reference_id (e.g. the order behind a movement) are included only when the token also holds read_orders; without it the movement row is returned with those fields omitted. Rows are retained for the window reported by the limits endpoint.

Returns items whose available stock (quantity - reserved) is at or below the configured threshold, with the positive deficit (threshold - available). Covers per-location and overall thresholds for directly tracked simple products and variants plus inventory groups; filter by location or overall scope, item type, or location. App tokens see merchant-managed locations and locations owned by their own active installation, never another app's locations.

Returns open, successfully applied reservation slices for simple products, variants and inventory groups, newest first. Narrow the listing to one item with source_type and source_id, and to one location with location_id. Each row is stock held for one order line at one location: state provisional while the shopper is paying (it counts in checkout_held until expires_at) or committed once the order is placed and paid or confirmed (it counts in order_committed). state is the authoritative applied state, not a pending desired state. Released and fulfilled stock is not listed; read commitment activity for that history. While an order's stock change is still being applied its rows are left out, so the rows add up to a location's checkout_held and order_committed once it applies. source_type (product, variant or group), source_id and sku name the item. Pages are keyed: pass the response's next_cursor as cursor to read the next page with the same filters; an empty next_cursor means there are no more rows. Order ids, item ids, and order numbers are included only when the token also has read_orders; internal transition status, errors, and operation ids are never exposed through the Store API. App tokens see merchant-managed locations and their own app-managed locations, never another app's locations.

Returns the append-only lifecycle ledger for successfully applied provisional holds, commitments, releases, reacquisitions, fulfillment consumption, and cancelled fulfillments, newest first. Narrow it to one item with source_type and source_id, one location with location_id, an event type, or a date range in the store timezone. event_type is provisional_held (a checkout hold started), committed (units committed to a placed order), released (held units became available again), reacquired (released units were held again), fulfilled (units left stock with a fulfillment) or fulfillment_reversed (a cancelled fulfillment put its units back). reason says why: order_created (an order was placed or an edit added units), payment_captured (the payment completed; with reacquired, a late payment held the same units again after its hold had been released), payment_retry (the shopper retried a payment), payment_failed or provider_init_failed (the payment failed or could not be started), checkout_hold_expired (the checkout hold duration ran out), order_released (the order was cancelled or removed), order_edited (an order edit or refund removed units), order_edit_abandoned (an unsaved order edit was discarded), order_create_failed (an order that could not be completed returned units sold on commit), order_fulfilled (units shipped), sold_without_shipping (items that don't need shipping left stock when the order was committed) or fulfillment_cancelled (a fulfillment was cancelled). reserved_after, checkout_held_after and order_committed_after are the location's numbers right after the event. source_type, source_id and sku name the item. Pages are keyed: pass the response's next_cursor as cursor to read the next page with the same filters; an empty next_cursor means there are no more rows. This is separate from physical stock movement history. Order ids, item ids, and order numbers are included only when the token also has read_orders; internal pending-operation and error details are never exposed through the Store API. App tokens see merchant-managed locations and their own app-managed locations, never another app's locations.

Applies up to max_batch_size rows in one database transaction: every row applies or none do. Each row addresses an item by SKU — simple product, variant, or inventory group resolve identically — at the batch location_id or its own location_id, and either adjusts by a signed delta (adjust) or writes an absolute quantity (set). A SKU may appear only once per location in a batch. Stock cannot change at an archived location: such a row fails the batch (inactive locations stay writable so stock can be corrected or zeroed before archiving). A set row may carry expected_quantity: the row is then a compare-and-set against the current on-hand quantity, and when they differ the whole batch is refused with 409 STOCK_LEVEL_EXPECTED_QUANTITY_MISMATCH and nothing changes. When any row fails, the response is that row's own error code with details.row (1-based), details.sku and details.location_id, and no row is applied. Send a stable Idempotency-Key when retrying: keys are scoped to your app (or the merchant user), UUIDs are canonicalized before comparison, an identical replay within 7 days returns the original result without a second movement, audit entry or webhook, and reusing a key for different input returns 409 STOCK_WRITE_IDEMPOTENCY_CONFLICT. App tokens may target merchant-managed locations and locations owned by their own active installation; they cannot write another app's location. Every applied row writes the movement ledger with your app as the actor, re-evaluates low-stock, and emits inventory_levels/update. Deltas are safe under concurrency; use set with expected_quantity when reconciling a physical count.

Returns paginated transfers with a stable transfer_number, status, endpoint ownership, locations, item counts, and total quantity. Filter by status, source location, destination location, or date range; search matches transfer number, UUID, merchant reference, or endpoint location name. Merchant callers can read all store transfers. App callers see transfers whose endpoints are merchant-managed or owned by that same app; another app's managed location and transfer remain undiscoverable. Writes are narrower: merchant tokens may mutate merchant-managed endpoints, while app tokens may mutate merchant-managed endpoints and endpoints owned by their own active installation. Pending and in-transit transfers protect their product, variant, or inventory-group references from deletion. Completed and cancelled transfers keep immutable title and SKU snapshots if a referenced catalog resource is later deleted.

Returns the transfer, its status history timestamps, and every line item with quantities. Each line includes resource_deleted. It is false while the referenced product, variant, or inventory group exists, and true when a terminal transfer is displaying the immutable title/SKU snapshot of a resource deleted later. Active transfers cannot enter this state because catalog deletion is blocked until the transfer is completed or cancelled.

Creates a pending transfer. Each item contains exactly one identifier matching its item type. Simple products and variants must use direct tracked inventory; when one is backed by an inventory group, transfer the group instead so a stale direct row can never move. Quantities are validated against available stock at the source location. Pending transfers hold nothing. Marking the transfer in_transit atomically moves the source units into reserved/other_held so orders cannot sell stock that is travelling. App tokens may use merchant-managed locations and locations owned by their own active installation, but cannot discover or mutate another app's locations. Send a stable Idempotency-Key when retrying creation: UUIDs are canonicalized before comparison, an identical replay returns the existing transfer without a second audit entry or webhook, and reuse for different input returns 409.

Moves the transfer through its lifecycle: pending → in_transit (ship) or cancelled; in_transit → completed (receive) or cancelled. Shipping holds the source units without changing physical on hand. Setting completed receives every unit that is still unaccounted for as received — the same as one receipt through the receive endpoint — consuming that part of the source transfer hold, decrementing source on hand, and incrementing destination on hand atomically with paired transfer_out and transfer_in movement rows. Units already recorded by earlier receipts are not moved again. Cancelling an in-transit transfer, including a partially received one, releases only the units that are still held; received, short and damaged units stay as recorded. Every availability or physical change emits inventory_levels/update.

Applies one valid lifecycle transition to up to 100 transfers. The complete batch is serialized and committed in one transaction: if any id is missing, duplicated, unwritable, has an invalid transition, or cannot reconcile its reservation safely, no transfer or inventory row changes. Repeating an already-applied target status is safe.

Records one receipt for some or all lines of an in_transit transfer; both the source and destination must still be active locations. For each line send received_quantity, short_quantity and damaged_quantity (whole numbers, at least one unit per line); together they may not exceed the line's remaining_quantity. Received units leave the source (on hand and transfer hold) and are added to destination on hand with paired transfer_out/transfer_in movements. Short units never left the source: their transfer hold is released so they become available at the source again, with no movement row. Damaged units leave the source on hand and hold and are written off with a transfer_damaged movement; they are not added to the destination. Receipts can be repeated until every unit of every line is accounted for; the receipt that accounts for the last unit completes the transfer. Each receipt commits atomically, emits inventory_levels/update for every changed level and transfers/received, and the completing receipt also emits transfers/status_changed. Concurrent receipts serialize on the transfer. Send a stable Idempotency-Key when retrying: an identical replay returns the original transfer without recording a second receipt; reuse for different input returns 409.

Deletes a transfer that has not shipped. Transfers that are in transit, completed, or cancelled are immutable history and cannot be deleted.

Deletes up to 100 pending transfers. In-transit, completed, and cancelled transfers are immutable operational history. If any selected transfer is missing, duplicated, immutable, or not writable by the caller, none are deleted. Every deleted transfer emits transfers/delete in the same transaction.

Returns customer "notify me when available" requests with product, status, and lifecycle timestamps — restock demand data for planning. Contact details (email or phone) are PII: they are returned only when the token also holds read_customers, and arrive redacted otherwise. The response's can_view_contact flag reports which mode you are in. Because contact is the searchable field, using search also requires read_customers; this prevents a redacted caller from inferring a subscription through result counts.

Returns the paging, search, status, contact-type, and sorting contract used by restock-request list clients.

Returns a stable zero-filled count for every supported status. Requests whose expiry time has passed are atomically transitioned from pending to expired before the counts are read.

Queues the same email or SMS delivery used by automatic restock notification. Alerts must be enabled and the product must be active with sellable stock. Expired, queued and already-notified requests are not claimed. Enqueued counts are not delivery confirmations; read request statuses for provider acceptance or failure.

Returns whether capture is enabled, how long new requests remain pending, whether notifications send automatically when stock is available again, and the accepted expiry range.

Replaces the three settings together. Unknown fields are rejected. Disabling capture prevents new requests; existing pending requests retain their lifecycle and can still be reviewed.