# Starshipit API fundamentals
URL: https://support.starshipit.com/articles/14700000001018-starshipit-api-fundamentals
Canonical: https://support.starshipit.com/articles/14700000001018-starshipit-api-fundamentals
Markdown: https://support.starshipit.com/articles/14700000001018-starshipit-api-fundamentals.md
Updated: 2026-06-18

> For the complete documentation index, see [llms.txt](https://support.starshipit.com/llms.txt).

> Understand Starshipit API base URL, headers, rate limits, pagination, retries, and error handling.

Use these fundamentals when you design an integration for the core Starshipit API. This API is the main Starshipit developer API and covers order import, label printing, rates, manifests, tracking, webhooks, and Product Catalogue workflows.

If you are building against Starshipit WMS inventory or warehouse workflows, use [WMS API fundamentals](/articles/developer-center/starshipit-wms-api/wms-api-fundamentals) instead.

## Base URL and headers

Use the Starshipit API base URL:

```text
https://api.starshipit.com
```

Every JSON request to `https://api.starshipit.com` should include:

| Header | Value |
| --- | --- |
| `Content-Type` | `application/json` |
| `StarShipIT-Api-Key` | Your API key from **Settings > API** |
| `Ocp-Apim-Subscription-Key` | Your subscription key from **Settings > API** |

The API key controls which Starshipit account your request accesses. The subscription key controls your rate limit and API access tier.

## Rate limits

Developer API access allows two requests per second. Production API access requires approval and uses a higher rate limit.

When you receive `429 Too Many Requests`, queue the work and retry with backoff. Do not immediately repeat the same request in a tight loop.

Batch work where possible. For order imports, use `POST /api/orders/import` to create multiple orders in one request instead of sending one request per order.

## Order creation timing

Create orders before the warehouse needs to print labels. After an order is created, Starshipit can run background work such as rules, courier rating, validation, and service selection.

If your integration creates an order and immediately tries to print it, the print request can wait on work that Starshipit could have completed earlier. Creating orders ahead of the fulfilment step keeps printing faster and makes failures easier to investigate before staff need the label.

## Pagination

Some list endpoints use page, page size, skip, status, or search parameters. When you build a sync job:

1. Store the last successful sync time or cursor your workflow can rely on.
2. Request a bounded page size.
3. Process each page before requesting the next page.
4. Stop when the endpoint returns no more records.
5. Log the page or query values used for each request.

## Idempotency and duplicate protection

Design write actions so retries are safe. Starshipit integrations commonly protect against duplicates by checking stable identifiers before repeating a write.

| Action | Duplicate protection |
| --- | --- |
| Create order | Reuse the source order number and check whether the order already exists before retrying. |
| Print label | Check shipment or print status before creating another label. |
| Update order | Apply only fields your source system owns and verify the order status first. |
| Webhook processing | Store processed event identifiers or a stable combination of order number, tracking number, status, and timestamp. |

## API compatibility

Starshipit aims to maintain backwards compatibility for existing API integrations. Avoid building against deprecated endpoints for new work, and retest critical flows after you change your own integration, Starshipit account setup, courier setup, or rules.

## Error handling

Handle these statuses explicitly:

| Status | Meaning | Integration response |
| --- | --- | --- |
| `400` | The request body or parameters are invalid. | Log the validation response and surface the order or product for correction. |
| `401` | Credentials are missing or incorrect. | Stop retries and check both API headers. |
| `403` | The account or key cannot perform the action. | Check API access, permissions, and the endpoint family. |
| `404` | The endpoint or record was not found. | Confirm the base URL, path, and identifiers. |
| `429` | The rate limit was exceeded. | Retry later with backoff. |
| `5xx` | Starshipit or an upstream dependency could not complete the request. | Retry cautiously and alert if failures continue. |

## Timeouts and retries

Use short, bounded retries for transient network or `5xx` failures. Retry only after the underlying condition can plausibly change.

Do not retry forever when the response says the payload is invalid, the order has already been printed, credentials are wrong, or a carrier service is unavailable.

## Related guides

- [Authentication and access](/articles/developer-center/getting-started/authentication-and-access)
- [Testing guidance](/articles/developer-center/getting-started/testing-guidance)
- [Troubleshoot API integrations](/articles/developer-center/getting-started/troubleshooting-api-integrations)