Inventory

This guide covers keeping availability true: how stock is reported to the Platform, how to update it as it changes, and how to handle the moment: inevitable in any integration: when the Platform's number and your warehouse's number disagree. The failure this guide exists to prevent is not a wrong number on a page; it is selling something that cannot ship. Endpoint detail is in Inventory Endpoints; the concepts in Core Concepts apply throughout.

Goal and prerequisites

Goal: at any moment, the availability the Platform shows for your products matches what you can actually ship, closely enough that oversell is rare and handled cleanly when it happens.

Prerequisites: products already in the catalog with stable product and variant codes (Catalog), an API key with inventory scope, and a stock source on your side: a warehouse system, an ERP, or a count process: whose numbers you trust more than any spreadsheet.

How availability works

Availability is reported per variant, per location where your account holds stock in more than one place. Two facts make up a report

• Quantity on hand: the count you can ship. Where your supply chain reports only in-or-out rather than counts, report the signal you have honestly; do not invent a count.
• Availability state: whether the variant may be sold at all right now. A variant can hold stock and still be unavailable (a recall, a quality hold), and it can be orderable at zero stock only where backorder is genuinely offered for that item.

The Platform combines your report with the product's own state: a variant reporting in stock does not sell while its product is withdrawn or unpriced. Availability you report is a promise the storefront repeats; report conservatively.

Step 1: Send an initial stock load

For each variant, send its quantity and state through Inventory Endpoints, keyed by the identifiers you established in the catalog step. Send an Idempotency-Key (Idempotency Keys) with every write batch so a retried submission is applied once. Record the response per variant: accepted, or rejected with an error code (Error Codes) that names what to fix: most often a variant code that does not match a catalog record, which means the catalog step and the inventory step disagree about identity and reconciliation comes before more stock sends.

Step 2: Keep it current

Stock that is loaded once and never updated is wrong by the end of the day. Choose the cadence that matches how fast your stock moves

• Change-driven updates are best: when a receipt, a pick, or an adjustment changes a variant's quantity in your system, send the new quantity to the Platform promptly.
• Scheduled deltas are acceptable: send what changed since the last run, on a fixed cadence, and track the high-water mark so a failed run re-sends its window rather than skipping it.
• Full refreshes are the fallback and the reconciliation tool, not the steady state: they cost the most rate budget (Rate Limit Headers) and carry the least new information.

Never let two of your systems report stock for the same variant on different cadences; conflicting reports oscillate, and the storefront shows the oscillation to buyers.

Step 3: Revalidate before commitment

A reported quantity is a signal, not a reservation: other channels sell from the same shelves. The discipline that prevents oversell

1. When an order arrives for your products, check your own current stock before you confirm you can fulfill it, using your live numbers rather than the last report you sent.
2. If the item cannot ship, act immediately through the fulfillment flow: see Fulfillment and Orders: so the order is cancelled or substituted and the buyer is refunded or informed without delay, never silently converted to a backorder.
3. Correct the Platform report in the same motion, so the storefront stops selling the item you just found missing.

Backorders and low stock

Offer backorder on a variant only when you can state, honestly, when it will ship. Where the API supports a low-stock threshold or an expected-restock date for your account, keep them current; a buyer told "low stock" who receives the item promptly trusts the signal, and a buyer sold an indefinite wait does not. When stock hits zero and no backorder is offered, report zero promptly: every hour a sold-out item stays listed produces orders you must disappoint.

Failure handling

• 400 / validation errors: the quantity or the variant reference is malformed. Fix the record at the source.
• 404: the variant does not exist in the catalog for your account. Load or correct the catalog first; do not create stock for items the catalog does not hold.
• 429: you are bursting updates faster than your tier allows. Batch, slow the cadence, and honor the headers (Rate Limit Headers); stock updates are exactly the traffic feeds and batching exist for at volume (Feeds and Bulk Data).
• Disagreement between your count and the Platform's display: trust your warehouse for what you can ship, correct the report, and treat repeated disagreement as an integration defect to find (usually two reporters, or a missed change window), not as weather.

What good looks like

Your stock source is the only reporter; updates flow on change; zero is reported as promptly as plenty; orders are revalidated against live stock before confirmation; and a scheduled reconciliation compares your counts against the Platform's and alerts on drift. Inventory integrations earn trust by being conservative: better to show "low stock" and deliver fast than to show "in stock" and apologize later.