# 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-07-20

> 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).
- Choose a test product and store its `productId`.
- Choose a receiving location and store its `locationId`.
- Confirm the API key can view and manage purchase orders and receive stock.
- Use a test account or test records before you receive live warehouse inventory.

:::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",
    "total": 125,
    "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` and calculate the quantity that remains to receive.
2. Confirm the `targetLocationId` exists and allows the product.
3. Send the receiving request. Use `quantityReceiving` for the quantity in this transaction.

```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",
    "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! Items received directly to final locations.",
  "stagingItemsCount": 0,
  "crossDockItemsCount": 0,
  "directItemsCount": 1,
  "workflowMode": "direct"
}
```

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

The public WMS API reference does not document a general idempotency key for these writes.

- 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.
- If a receiving response has `"success": false`, correct the problem in `message` before retrying. Some workflow validation failures use this result with an HTTP success status.

`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. A `403` means the key lacks purchase-order or receiving permission. 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)