# Quickstart: Authenticate and look up WMS inventory
URL: https://support.starshipit.com/articles/14700000001026-quickstart-authenticate-and-look-up-wms-inventory
Canonical: https://support.starshipit.com/articles/14700000001026-quickstart-authenticate-and-look-up-wms-inventory
Markdown: https://support.starshipit.com/articles/14700000001026-quickstart-authenticate-and-look-up-wms-inventory.md
Updated: 2026-07-20

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

> Authenticate with the WMS API, look up inventory, and work through paginated results.

Use this quickstart to authenticate with the Starshipit WMS API, find a product by SKU, and store the WMS IDs needed for later warehouse workflows.

## Before you begin

- Confirm your account uses the Starshipit WMS add-on.
- Get the Starshipit API key for the WMS account you want to access.
- Store the API key in a secret manager and keep it out of source code and logs.
- Choose a test product that already exists in that account.
- Confirm the API key can view inventory.

WMS API requests use `https://wms.starshipit.com`. Do not send these requests to the core Starshipit API domain.

## Look up inventory

1. Replace `WIDGET-001` with the SKU you want to find.
2. Send a bounded inventory request with the `starshipit-api-key` header.

```bash
curl --request GET \
  --url "https://wms.starshipit.com/api/inventory?viewMode=product&search=WIDGET-001&page=1&pageSize=25" \
  --header "starshipit-api-key: YOUR_STARSHIPIT_API_KEY"
```

3. Confirm the response contains the expected product and pagination fields.

```json
{
  "items": [
    {
      "id": "product-123",
      "sku": "WIDGET-001",
      "name": "Super Widget",
      "trackingType": "NONE",
      "allocationRule": "FIFO",
      "quantityOnHand": 60,
      "quantityIncoming": 10,
      "quantityReserved": 5,
      "quantityCommitted": 8,
      "quantityAvailable": 52,
      "inventories": [
        {
          "locationId": "loc-source-456",
          "locationName": "A-01-01",
          "quantityOnHand": 50
        },
        {
          "locationId": "loc-target-789",
          "locationName": "B-02-03",
          "quantityOnHand": 10
        }
      ],
      "detailedInventories": [],
      "reservedOrders": [],
      "pendingOrders": []
    }
  ],
  "totalCount": 1,
  "page": 1,
  "pageSize": 25,
  "totalPages": 1
}
```

4. Store `items[0].id` as the `productId` for later requests.
5. Store the relevant `locationId` values if your next workflow needs them.
6. Check `quantityAvailable`, not only `quantityOnHand`, before you plan a stock-consuming action.

The example IDs in this article are illustrative and will not work in your account. WMS endpoints use record IDs rather than SKUs, barcodes, product names, or location names for follow-up actions.

## Process every page

Inventory uses a 1-based `page` and a `pageSize` with a maximum of `100`.

1. Process every item in the current response.
2. Increment `page` by one.
3. Send the next request.
4. Stop after `page` reaches `totalPages`.

Do not assume one response contains every matching record. Log the search and pagination values with each request so you can resume a failed sync safely.

## Handle authentication and lookup errors

| Response | What to do |
| --- | --- |
| `400` | Add the missing header or correct the query. Do not retry the same request unchanged. |
| `401` | Stop the workflow and replace or correct the API key. |
| `403` | Confirm the account and inventory-view permission. |
| `404` | Confirm the WMS domain and that the key belongs to a WMS account. |
| `429` | Queue the request and retry later with exponential backoff and jitter. |
| `5xx` or timeout | Retry the read with bounded backoff. Alert if failures continue. |

## Related guides

- [Move WMS stock safely](/articles/developer-center/starshipit-wms-api/quickstart-move-wms-stock-safely)
- [Create and receive a WMS purchase order](/articles/developer-center/starshipit-wms-api/quickstart-create-and-receive-wms-purchase-order)
- [WMS API fundamentals](/articles/developer-center/starshipit-wms-api/wms-api-fundamentals)
- [WMS API reference](/developers/api-reference/wms)