Integration Journey
The four stages every Starship integration passes through, with the concrete deliverables at each stage
Integration Journey
Every production Starship integration passes through four stages. They're not strictly linear — you may iterate back to earlier stages as requirements solidify — but the dependency arrows below are real. Skipping them leads to the common failure modes we've seen: quoting engines that don't match billing, retry loops that double-charge, production rollouts with no sandbox parity.
Each stage has a concrete exit criterion — see the table below. Do not skip a stage to hit a launch deadline; the cost of debugging a production incident far exceeds two more days of sandbox testing.
Stage-by-stage deliverables
Stage 0 — Access
| Exit criterion | How to verify |
|---|---|
| You have a sandbox API key + secret | echo $X_API_KEY | head -c 8 returns sk_test_ |
| Your egress IPs are whitelisted | curl https://api-playground.starshiprewards.com/api/v1/products -H "X-API-Key: $K" -H "X-API-Secret: $S" returns 200 |
| You have a copy of your negotiated discount sheet | You know which products have CPD rows and what the % is |
Blockers: IP whitelist changes take 24–48 h. Request yours from your Starship contact on day one.
Stage 1 — Read-only Explore
| Exit criterion | How to verify |
|---|---|
| You can list products, filter by country + currency, and paginate | Your catalog ingestion runs without errors |
You can fetch a single product and read its delivery_time | Your UI shows "Delivered instantly" vs "Delivery within hours" copy correctly |
| You can resolve a Charges API quote for a known product | Your checkout "Pay now" amount matches the API total exactly |
Common mistakes: caching delivery_time for hours (it can flip with each inventory pump — re-quote at order time), hardcoding a CPD % in your frontend (CPD changes without notice; trust the Charges API).
Stage 2 — Quote & Order
| Exit criterion | How to verify |
|---|---|
| You've funded your sandbox wallet and placed 20+ sandbox orders | Wallet balance decreases exactly by the quoted total for each order |
Both INSTANT and DELAYED delivery paths exercised | You've received order-pending-then-delivered webhook sequences |
Your order creation uses Idempotency-Key on every call | A simulated timeout + retry does not double-charge |
Your GET /orders/:id polling backs off after initial 60 s | Your polling doesn't trigger 429 E_REQUEST_THROTTLED under load |
Common mistakes: omitting Idempotency-Key ("my retries are rare so it won't matter"), polling too fast (429), assuming PENDING means "in progress" (it means "parked, awaiting admin or inventory pump").
Stage 3 — Production Canary
| Exit criterion | How to verify |
|---|---|
| Production credentials provisioned in a separate env from sandbox | Sandbox traffic cannot accidentally hit prod due to an env-var typo |
| 1–5 % of live traffic routed to Starship for at least 48 h | Your A/B metrics show no user-facing regression |
| Webhook endpoint is reachable from Starship's egress IPs | No failed deliveries in the stats response |
| Reconciliation job matches Starship's ledger to yours daily | Zero unexplained discrepancies over a 48 h window |
Common mistakes: reusing sandbox credentials in prod (they'll 401 — embarrassing at best, outage at worst), skipping the canary because "sandbox worked" (prod has different vendors, different inventory depth, different FX timing).
Stage 4 — Full Production
| Exit criterion | How to verify |
|---|---|
Alerting on orders PENDING > 24 h | An ops dashboard surfaces them; someone is paged |
| Alerting on wallet balance below a threshold you can live with | You get a day's notice before you'd run out |
| Runbook for "Starship is down" exists and has been rehearsed | On-call knows how to fail open (disable rewards temporarily) vs fail closed (queue and replay) |
What to build in parallel
Don't wait until Stage 3 to build these — they're load-bearing and take real engineering time:
- A wallet-balance dashboard — otherwise no one notices until orders start failing with
PAYMENT_REQUIRED. - A
PENDINGstuck-orders report — orders that never closed out need human attention. - Event de-duplication in the webhook handler — Starship may retry a webhook after a lost 2xx, and your handler must not double-process.
- A reconciliation job — a nightly diff of your ledger vs. Starship's. Silent 0.05-per-order drift compounds to real money over a quarter.
Next
→ Quickstart — five curl commands, sandbox to first voucher