Inventory Endpoints

This document covers the inventory endpoints: reading stock levels for your products, recording stock changes, and reviewing the history of movements behind a level. Stock is tracked per variant and per location. The quantity a buyer can purchase is the quantity available: on hand, minus quantities already committed to open orders.

Access through the developer API is issued by the Company and is limited by seller type: manufacturer and supplier accounts receive API access for importing data, under the Developer Agreement and the API Access Tiers. Adjustment endpoints require the import entitlement. Nothing in this document grants broader access.

Endpoints

Method	Path	Purpose	Access
GET	`/inventory`	List stock levels for your variants, paginated	Any API key
GET	`/inventory/{variant_id}`	Read the level for one variant, by location	Any API key
GET	`/inventory/locations`	List the stocking locations on your account	Any API key
POST	`/inventory/adjustments`	Record a stock change	Import entitlement
GET	`/inventory/movements`	List recorded stock changes, newest first	Any API key

All paths are relative to the base URL https://www.aapawz.com/api. Collections paginate as specified in Pagination and Filtering (Pagination & Filtering). Every adjustment accepts an Idempotency-Key header (Idempotency Keys) and shall carry one: a retried adjustment must never move stock twice.

The inventory level object

{
  "variant_id": "var_51hd02",
  "product_id": "prod_8f3ka9",
  "seller_sku": "ACME-DOGFOOD-10LB",
  "location_id": "loc_memphis_01",
  "quantity_on_hand": 140,
  "quantity_reserved": 12,
  "quantity_available": 128,
  "updated_at": "2026-10-14T08:15:44Z"
}

Quantities are whole units. quantity_available is always quantity_on_hand minus quantity_reserved; do not compute availability yourself from stale reads: read the level. Field definitions are in Data Types and Enums. Products and variants are defined in Catalog Endpoints.

Recording a stock change

Stock changes are recorded as adjustments with a reason. The Platform applies the change and keeps the movement in history permanently; a level is never edited directly and a movement is never deleted.

POST /inventory/adjustments
Authorization: Bearer <your-api-key>
Idempotency-Key: receiving-2026-10-14-po-4471
Content-Type: application/json

{
  "variant_id": "var_51hd02",
  "location_id": "loc_memphis_01",
  "change": 60,
  "reason": "received",
  "note": "Purchase order 4471"
}

change is a signed integer: positive to add stock, negative to remove it. An adjustment may not take quantity_on_hand below the quantity already reserved for open orders; such a request fails with 422 and code insufficient_unreserved_stock.
reason is required and is one of received, sold, returned, damaged, expired, correction, count. Use count with a change that brings the level to a physically counted total only when accompanied by a note stating the counted total.
sold and returned movements arising from marketplace orders are recorded by the Platform itself when an order is placed or a return is received (Orders Endpoints, Returns Endpoints). Do not record them again for the same order.

A successful adjustment returns 201 and the movement object

{
  "id": "mov_93jd71",
  "variant_id": "var_51hd02",
  "location_id": "loc_memphis_01",
  "change": 60,
  "reason": "received",
  "note": "Purchase order 4471",
  "quantity_on_hand_after": 140,
  "created_at": "2026-10-14T08:15:44Z"
}

Reading movement history

GET /inventory/movements returns the movements for your account and accepts variant_id, location_id, reason, and date-range filters (Pagination and Filtering (Pagination & Filtering)). Use it to reconcile your warehouse records against the Platform's levels: if the totals disagree, the movement history is the record of what the Platform applied, in order.

Holds and restricted stock

Stock under a compliance hold cannot be sold and is excluded from quantity_available while the hold stands; the hold and its reason are visible on the level object as hold: true and hold_reason. Holds are imposed and released under Governance Endpoints, not through these endpoints. Stock of a brand-restricted product follows the brand rules in Brand and Manufacturer Endpoints.

Events and errors

Subscribe to inventory.low and inventory.out events to react when a variant runs low or out (Webhook Event Schemas); set the low-stock threshold in the Seller Center. Fulfillment draws on these levels when a shipment is created (Fulfillment Endpoints).

Status	Code	Cause
404	`not_found`	No variant or location with that identifier exists in your account
422	`validation_failed`	`change` is zero or missing, or `reason` is not an allowed value
422	`insufficient_unreserved_stock`	The change would take on-hand stock below the reserved quantity
409	`location_inactive`	The location no longer accepts stock changes

Error bodies follow Error Codes.

Catalog Endpoints

Orders Endpoints