ShipStation API

What This Does

The ShipStation client is how we read and write customs data. It handles authentication (Basic auth with encrypted credentials), rate limiting (ShipStation allows ~40 requests per minute), automatic retries on 429/5xx errors with exponential backoff, and building/parsing API URLs and responses.

Why It Matters

ShipStation's API is the external system we modify. If we don't handle rate limits correctly, we'll get blocked. If we don't retry on transient errors, orders will fail unnecessarily. If we don't authenticate properly, nothing works at all.

How It Works

1. 1.The client is initialized with a Base64-encoded 'apiKey:apiSecret' string from KMS decryption.
2. 2.Every request goes through the rate limiter first — if we're approaching the limit (fewer than 10 remaining), we wait until the rate limit window resets.
3. 3.On 429 (rate limited): honor the Retry-After header and wait, then retry up to 3 times.
4. 4.On 5xx (server error): exponential backoff (1s, 2s, 4s), retry up to 3 times.
5. 5.On 4xx (client error): don't retry — it's a permanent error (bad request, not found, etc.).
6. 6.Rate limit state is tracked from ShipStation's response headers (X-Rate-Limit-Remaining and X-Rate-Limit-Reset).

Key Decisions

• ●ShipStation uses POST /orders/createorder for BOTH creating AND updating orders. When you include the orderId in the body, it updates the existing order.
• ●We push the ENTIRE order object back to ShipStation, not just the customs items. This preserves all fields and avoids accidentally clearing data.
• ●Rate limiter proactively throttles when remaining requests drop below 10 (out of ~40), rather than waiting for a 429.

What Could Go Wrong

• ●If rate limiting fails, ShipStation blocks our API key for a window (up to 60 seconds).
• ●If we only pushed partial order data, we could accidentally delete fields like shipping method or weight.
• ●If the retry logic were too aggressive, we'd burn through rate limits on retries alone.