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

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

> Understand WMS API base URL, authentication header, retries, errors, and integration habits.

Use these fundamentals when you design an integration for the Starshipit WMS API. Starshipit WMS is an add-on to Starshipit for warehouse workflows such as jobs, products, inventory, locations, purchase orders, picking, packing, putaway, replenishment, stocktake, and stock movements.

If you are building shipping, labels, rates, manifests, tracking, webhooks, or Product Catalogue workflows, use [Starshipit API fundamentals](/articles/developer-center/starshipit-api/api-fundamentals) instead.

## Base URL and headers

Use the WMS API base URL:

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

Every WMS request should include:

| Header | Value |
| --- | --- |
| `starshipit-api-key` | Your Starshipit API key for the WMS account. |

Use the [WMS API reference](/developers/api-reference/wms) to confirm the exact request parameters and body for each endpoint.

## Request design

When you build a WMS integration:

1. Keep the WMS API client separate from any core Starshipit API client.
2. Log the endpoint path, method, response status, response body, and source-system identifier.
3. Store stable IDs returned by WMS endpoints so retries and follow-up actions target the same record.
4. Re-read records before high-impact actions when warehouse state may have changed.
5. Test with a small workflow before moving real warehouse volume.

## Pagination and filters

List endpoints can use query parameters such as page, limit, search, filters, or status fields. When you build sync jobs:

- Request bounded page sizes.
- Process each page before requesting the next page.
- Store the last successful sync time, cursor, or source-system checkpoint your workflow can rely on.
- Log the filter and pagination values used for each request.

## Duplicate protection

Design write actions so retries do not create duplicate warehouse work.

| Action | Duplicate protection |
| --- | --- |
| Create or update a product | Match by stable SKU or product ID before retrying. |
| Move or adjust stock | Store the source transaction ID and reconcile stock movement results. |
| Create a job or workflow action | Check the current job status before repeating the action. |
| Pick, pack, or replenish | Confirm the operation has not already progressed to the next warehouse state. |

## 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 record for correction. |
| `401` | Credentials are missing or incorrect. | Stop retries and check the `starshipit-api-key` header. |
| `403` | The account or key cannot perform the action. | Check account access and WMS permissions. |
| `404` | The endpoint or record was not found. | Confirm the base URL, path, and identifiers. |
| `409` | The requested action conflicts with the current warehouse state. | Re-read the record and decide whether to retry, skip, or send for manual review. |
| `429` | The integration sent too many requests. | Queue the work and retry later with backoff. |
| `5xx` | WMS or an upstream dependency could not complete the request. | Retry cautiously and alert if failures continue. |

## 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)
- [WMS API reference guide](/articles/developer-center/starshipit-wms-api/wms-api-reference-guide)