# Quickstart: Create and receive a WMS purchase order
URL: https://support.starshipit.com/articles/14700000001028-quickstart-create-and-receive-a-wms-purchase-order
Canonical: https://support.starshipit.com/articles/14700000001028-quickstart-create-and-receive-a-wms-purchase-order
Markdown: https://support.starshipit.com/articles/14700000001028-quickstart-create-and-receive-a-wms-purchase-order.md
Updated: 2026-11-16

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

> Create a WMS purchase order, receive its stock, and verify the completed receiving workflow.

Use this quickstart to find a supplier, create a WMS purchase order, receive one line, and verify the final purchase-order state.

## Before you begin

- Complete [Authenticate and look up WMS inventory](/articles/developer-center/starshipit-wms-api/quickstart-authenticate-and-look-up-wms-inventory).
- Ask your administrator to confirm `purchase-orders.view` for reading suppliers and purchase orders, `purchase-orders.manage` for creating purchase orders, and `receiving.*` for receiving stock.
- Choose a test product and store its `productId`.
- Choose a receiving location and store its `locationId`.
- Use a test account or test records before you receive live warehouse inventory.
- Enable cartons received in the account receiving settings before using the example with `cartonsReceived: 1`. Otherwise omit that field and expect `cartonsReceived: 0` when verifying the purchase order.
- Check the account over-receiving setting and under-receiving tolerance before receiving or completing the purchase order. **No limit** allows receiving above the ordered quantity; a percentage limit caps it. Completion still checks the under-receiving tolerance.

This example creates a standard WMS purchase order. For a Cin7 Core-linked order, read `GET /api/purchase-order/[id]/receiving-context` first. If it returns `mode: "invoice-first"`, follow the selected-invoice contract in the [WMS API reference](/developers/api-reference/wms#purchase-orders) before receiving stock.

:::warning
Receiving a purchase order changes warehouse inventory and can create putaway work. Start with one line and a small quantity.
:::

## Find the supplier

1. Retrieve suppliers.

```bash
curl --request GET \
  --url https://wms.starshipit.com/api/supplier \
  --header "starshipit-api-key: YOUR_STARSHIPIT_API_KEY"
```

2. Match the supplier in your source system, then store its `id`. Do not substitute the supplier name.

```json
[
  {
    "id": "supplier-456",
    "name": "ACME Widget Supply Co."
  }
]
```

## Create the purchase order

1. Use a purchase order number that is unique within the WMS account.
2. Send the create request.

```bash
curl --request POST \
  --url https://wms.starshipit.com/api/purchase-order \
  --header "starshipit-api-key: YOUR_STARSHIPIT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "poNumber": "ERP-PO-10042",
    "supplierId": "supplier-456",
    "status": "CREATED",
    "expectedArrivalDate": "2026-07-25",
    "lineItems": [
      {
        "productId": "product-123",
        "quantity": 10,
        "price": 12.5
      }
    ]
  }'
```

3. Store the top-level purchase order `id` and each returned line item `id` from the `201 Created` response.

```json
{
  "id": "po-def789",
  "poNumber": "ERP-PO-10042",
  "supplierId": "supplier-456",
  "accountId": "account-123",
  "createdDate": "2026-07-20T01:30:00.000Z",
  "status": "CREATED",
  "expectedArrivalDate": "2026-07-25T00:00:00.000Z",
  "cartonsReceived": 0,
  "supplier": {
    "id": "supplier-456",
    "accountId": "account-123",
    "name": "ACME Widget Supply Co."
  },
  "lineItems": [
    {
      "id": "line-789",
      "purchaseOrderId": "po-def789",
      "productId": "product-123",
      "quantity": 10,
      "price": 12.5,
      "quantityOrdered": null,
      "quantityReceived": 0,
      "quantityReceiving": null
    }
  ]
}
```

`purchaseOrderId` is the top-level `id`. `lineItemId` is the `id` inside `lineItems`. Do not use the purchase order number, product ID, or SKU in place of either ID.

## Receive the purchase order

1. Read `GET /api/purchase-order/po-def789`, store every `lineItems[].id`, and calculate the quantity that remains to receive.
2. Confirm the `targetLocationId` exists and allows the product.
3. Send the receiving request. Use a non-negative whole number in `quantityReceiving` for this transaction. Completion must satisfy the configured under-receiving tolerance for every line.

```bash
curl --request POST \
  --url https://wms.starshipit.com/api/purchase-order/receive \
  --header "starshipit-api-key: YOUR_STARSHIPIT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "purchaseOrderId": "po-def789",
    "expectedLineItemIds": ["line-789"],
    "receivingItems": [
      {
        "lineItemId": "line-789",
        "productId": "product-123",
        "quantityReceiving": 10,
        "targetLocationId": "loc-target-789"
      }
    ],
    "cartonsReceived": 1,
    "markPOComplete": false
  }'
```

4. Check both the HTTP status and the JSON `success` value.

```json
{
  "success": true,
  "message": "Receiving completed successfully! Products received directly to final locations.",
  "stagingItemsCount": 0,
  "crossDockItemsCount": 0,
  "directItemsCount": 1,
  "workflowMode": "direct"
}
```

The optional `expectedLineItemIds` contains the complete set of line IDs from the latest purchase-order response, including lines you are not receiving in this request. If lines have been added or removed, WMS returns `409` with `code: STALE_PURCHASE_ORDER`. Re-read the purchase order and review the revised lines before resubmitting. This check detects line-set changes; it does not replace checking received quantities before a retry.

The result depends on the target location and account receiving workflow. A staging location can create putaway work instead of adding stock directly to its final location.

Batch-tracked products require `batchNumber`. Serial-tracked products require one unique value in `serialNumbers` for each unit in `quantityReceiving`.

## Verify receiving

1. Retrieve the purchase order again.

```bash
curl --request GET \
  --url https://wms.starshipit.com/api/purchase-order/po-def789 \
  --header "starshipit-api-key: YOUR_STARSHIPIT_API_KEY"
```

2. Confirm `quantityReceived`, `status`, and `cartonsReceived` match the completed work.

```json
{
  "accountId": "account-123",
  "id": "po-def789",
  "poNumber": "ERP-PO-10042",
  "createdDate": "2026-07-20T01:30:00.000Z",
  "expectedArrivalDate": "2026-07-25T00:00:00.000Z",
  "status": "RECEIVED",
  "cartonsReceived": 1,
  "supplier": {
    "id": "supplier-456",
    "name": "ACME Widget Supply Co."
  },
  "lineItems": [
    {
      "id": "line-789",
      "productId": "product-123",
      "quantity": 10,
      "price": 12.5,
      "quantityReceived": 10,
      "quantityOrdered": 0,
      "quantityReceiving": 0,
      "product": {
        "id": "product-123",
        "sku": "WIDGET-001",
        "name": "Super Widget",
        "trackingType": "NONE"
      }
    }
  ]
}
```

## Retry uncertain writes safely

Purchase-order creation and standard receiving have no general idempotency key. Invoice-first receiving supports a persisted `submissionId` only when you send `invoiceReceipt`.

- If creation times out, call `GET /api/purchase-order?search=ERP-PO-10042&limit=10` and match the exact `poNumber` before retrying. WMS rejects a duplicate purchase order number.
- If receiving times out, retrieve the purchase order and compare `quantityReceived` with the value from before the request. Do not send the same quantity again when the first request may have succeeded.
- For an invoice-first request, look up `GET /api/purchase-order/[id]/receipts/[submissionId]` using the identity saved before the write. A returned receipt has `localStockCommitted: true` even when Cin7 Core synchronisation needs review; do not receive the invoice again. Only `INVOICE_RECEIPT_NOT_FOUND` states that no accepted receipt exists for that identity. A generic `404`, `503`, or timeout leaves the outcome uncertain.
- If WMS returns `409` with `code: STALE_PURCHASE_ORDER`, refresh the purchase order and rebuild `expectedLineItemIds` and the receiving request from its current lines.
- For HTTP `422`, inspect `"success": false`, `error`, and `message`. Correct the reported workflow problem, including any receiving tolerance violation, before retrying.

`GET /api/purchase-order` supports `limit`, but does not return page metadata. Narrow list requests with `status` or `search`, and do not treat `limit` as a paginated cursor.

A `400` response means the payload is invalid. For a `403`, confirm the API key belongs to the correct WMS account. Ask the account administrator to check the authenticated user’s WMS role and client access; contact Starshipit support if access is still denied. A `404` means an account or record ID was not found. Reconcile current state before retrying a `5xx` response or timeout.

## Related guides

- [Authenticate and look up WMS inventory](/articles/developer-center/starshipit-wms-api/quickstart-authenticate-and-look-up-wms-inventory)
- [WMS suppliers and purchase orders](/articles/starshipit-wms/inbound/starshipit-wms-suppliers-and-purchase-orders)
- [WMS receiving stock](/articles/starshipit-wms/inbound/starshipit-wms-receiving-stock)
- [WMS API reference](/developers/api-reference/wms)
