Core Concepts
Core Concepts
Mental models that every Starship integration should understand — fulfillment, order lifecycle, pricing, wallets, and webhooks
Core Concepts
These pages describe the mental models you need before wiring up specific endpoints. Skim them once and the rest of the API reference will make sense; skip them and you'll keep circling back to figure out why the API behaves the way it does.
| Concept | Why it matters |
|---|---|
| Fulfillment Model | Explains when orders fulfill synchronously vs. go async, and how inventory cache drives that decision. Controls your polling strategy. |
| Order Lifecycle | The state machine an order travels through, including every sub-status. Drives your reconciliation logic. |
| Pricing & Charges | How the final amount charged is computed — FX, client discount, vendor discount, fees. Drives your pre-order quote. |
| Wallets & Settlement | How wallet balances move when orders succeed, fail, or are refunded. Drives your accounting reconciliation. |
| Delivery Semantics | Poll vs. webhook; when to trust delivery_time; retry policy for webhooks. |
These concepts complement — they do not replace — the API reference. Once you've read them, head to Products, Orders, and Webhooks to wire up real calls.