Starship REST API

Authentication

Stateless auth. No sessions, no bearer tokens, no OAuth, no refresh flows. Every API request carries your partner key + secret on the headers. The server validates identity per-call; there is no server-side session state to expire or re-establish.

X-API-Key: pk_live_01HX9...
X-API-Secret: sk_live_...

Keys are issued per partner during onboarding, scoped to a single partner organization, bound to an IP allowlist, and can be rotated on request. They remain valid until explicitly revoked — no expiry, no re-auth cycle, no token refresh.

Why stateless: partner integrations live long-term; a fresh header-based signature on every request is simpler to operate than an OAuth dance with refresh tokens, and it keeps replay windows short.

Request signing · HMAC-SHA256

Identity alone isn't enough — every write request (POST, PUT, DELETE) is also HMAC-signed for integrity and replay protection. Compute an HMAC-SHA256 over the concatenated timestamp + method + path + body using your API secret, then attach:

X-Timestamp: 1744646400          # unix seconds, must be within 5 min of server time
X-Signature: t=1744646400,v1=7a2c4f...   # v1 = hex-encoded HMAC-SHA256

The t= prefix binds the timestamp into the signature (replay protection). Signatures older than the clock-skew window are rejected.

Reference signer (pseudo-code)

// Any language — 10 lines
ts  = unix_now()
msg = ts + method + path + body    // all strings, concatenated
sig = hmac_sha256(api_secret, msg).hex()

headers["X-API-Key"]    = api_key
headers["X-API-Secret"] = api_secret
headers["X-Timestamp"]  = ts
headers["X-Signature"]  = "t="+ts+",v1="+sig

Reference implementations (Go, Node, Python, PHP) are 15–30 lines each and shared with certified partners on request. A public OpenAPI 3.1 spec is on the roadmap; a Postman collection is available today.

Idempotency

Write endpoints that create state — POST /orders, POST /payouts — require an Idempotency-Key header. Retries with the same key return the original response without re-executing. Keys are retained for 24 hours.

Idempotency-Key: order-2026-04-14-a7f3c9b2

Rate limits

Limits are applied per API key, per endpoint class. The most relevant defaults:

• POST /orders — 100 req/min
• General /api/v1/* — 1000 req/hour
• Auth endpoints — 5 req/min

When limits are exceeded the API returns 429 Too Many Requests with a Retry-After header. Enterprise partners can negotiate higher limits per contract.

Error shape

Errors use standard HTTP status codes plus a structured body:

{
  "error": {
    "name":    "InsufficientInventory",
    "code":    "INSUFFICIENT_INVENTORY",
    "message": "No vouchers available for product amazon-gift-500"
  }
}

Every response also carries an X-Trace-ID response header when distributed tracing is enabled — quote it in support tickets so we can find the exact request.

Core endpoints

Catalog

Orders

Wallet & transactions

Webhooks

Reconciliation Planned · not yet built

Daily reconciliation matches every allocation against vendor-side records and surfaces drifts. Today this runs internally and is visible in the operator console; a public partner endpoint is in design. The shape below is the planned contract — subject to change before release. Tell us if you need it prioritized for your integration.

Planned response shape

{
  "date":           "2026-04-13",
  "summary": {
    "orders_total":      847,
    "vouchers_allocated": 1283,
    "matched":           1281,
    "drifted":           2,
    "unmatched":         0
  },
  "drifts": [
    {
      "order_id":        "ord_01HX9...",
      "vendor":          "voucherkart",
      "product_id":      "amazon-gift-500",
      "our_allocation":  "VOUCHER-A",
      "vendor_record":   "VOUCHER-B",
      "detected_at":     "2026-04-13T18:42:00Z",
      "resolution":      "pending"      // pending | resolved | escalated
    }
  ],
  "generated_at":   "2026-04-14T00:30:12Z"
}

Internal status today: reconciliation runs as a scheduled job, drifts are flagged in the operator console, and corrections happen via admin action. The public endpoint formalizes that pipeline so partners can poll their own daily summary instead of asking us. ETA depends on partner demand — it’s a small Go addition once we lock the contract.

Webhooks

Starship emits signed webhooks for lifecycle events. Your endpoint must return 2xx within 5 seconds or the delivery is retried with exponential backoff for 24 hours.

Event types (current)

• order.created — order accepted into the system
• order.processing — allocation in progress (typical: async path)
• order.delivered — all vouchers allocated and ready
• order.partially_delivered — some vouchers allocated, remainder pending or failed
• order.cancelled — order cancelled (admin action or partner request)
• order.refunded — wallet credit returned after cancellation
• voucher.issued — a specific voucher within an order has been issued

Roadmap: reconciliation-drift and wallet-balance-threshold events are tracked internally today and will be exposed as webhook events once we standardize the payload contract.

Sample payload

{
  "event":      "order.delivered",
  "event_id":   "evt_01HX9ABC...",
  "created_at": "2026-04-14T08:42:15Z",
  "data": {
    "order_id":       "ord_01HX9...",
    "status":         "DELIVERED",
    "total_amount":   500.00,
    "currency":       "USD",
    "fulfilled_from": "cache",
    "vouchers": [
      { "product_id": "amazon-gift-500", "expiry": "2027-04-14" }
    ]
  }
}

Voucher codes are delivered via a secure, separately-fetched endpoint — they are not included in webhook payloads. This protects them from log leakage and from clients that mishandle retry.

Environments

• Sandbox — https://api-playground.starshiprewards.com/api/v1. Mock inventory, no real vouchers issued, same stateless auth + HMAC-SHA256 signing model as production.
• Production — base URL issued privately to certified partners during onboarding. Access requires a passed sandbox certification and a signed MSA.

The companion admin surface for operator users is at admin-playground.starshiprewards.com (sandbox). Partner-API clients never need it — everything an integration needs lives under the /api/v1 prefix above.

Postman & samples

Shared with certified partners during onboarding:

• Postman collection — full request library with pre-request scripts that compute the HMAC signature from your sandbox keys
• Reference request signers in Go, JavaScript (Node), Python, PHP

Roadmap: a public OpenAPI 3.1 specification and official SDK packages (Go-first) are planned. Current partners typically integrate in a few hundred lines using the reference signers — we share them on request.