# Quickstart: Move WMS stock safely
URL: https://support.starshipit.com/articles/14700000001027-quickstart-move-wms-stock-safely
Canonical: https://support.starshipit.com/articles/14700000001027-quickstart-move-wms-stock-safely
Markdown: https://support.starshipit.com/articles/14700000001027-quickstart-move-wms-stock-safely.md
Updated: 2026-07-20

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

> Check available inventory, transfer WMS stock between locations, and verify the movement safely.

Use this quickstart to check available inventory, transfer a small quantity between two WMS locations, and verify both sides of the movement.

## 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`.
- Store the source and destination `locationId` values. Do not substitute location names.
- Confirm the API key can view inventory and move stock.
- Start with a non-tracked product or check the required batch or serial fields in the [Create Stock Movement endpoint](/developers/api-reference/wms#post-api-stock-movement-create-stock-movement).

:::warning
A stock movement changes warehouse inventory. Start with a small quantity and verify the result before increasing volume.
:::

This example transfers five units from `A-01-01` to `B-02-03`. A positive `change` moves stock from `transferLocationId` to `locationId`.

## Check stock before the transfer

1. Read the product in location view immediately before the transfer.

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

2. Confirm the source has enough available stock and the source and destination IDs are different.

```json
{
  "items": [
    {
      "id": "loc-source-456",
      "name": "A-01-01",
      "type": "PICK_FACE",
      "totalQuantity": 50,
      "productCount": 1,
      "products": [
        {
          "id": "product-123",
          "sku": "WIDGET-001",
          "trackingType": "NONE",
          "quantityOnHand": 50,
          "quantityCommitted": 5,
          "quantityAvailable": 45
        }
      ]
    },
    {
      "id": "loc-target-789",
      "name": "B-02-03",
      "type": "BULK_STORAGE",
      "totalQuantity": 10,
      "productCount": 1,
      "products": [
        {
          "id": "product-123",
          "sku": "WIDGET-001",
          "trackingType": "NONE",
          "quantityOnHand": 10,
          "quantityCommitted": 0,
          "quantityAvailable": 10
        }
      ]
    }
  ],
  "totalCount": 2,
  "page": 1,
  "pageSize": 100,
  "totalPages": 1
}
```

## Transfer the stock

1. Create a stable `reference` in your source system.
2. Send the transfer.

```bash
curl --request POST \
  --url https://wms.starshipit.com/api/stock-movement \
  --header "starshipit-api-key: YOUR_STARSHIPIT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "productId": "product-123",
    "locationId": "loc-target-789",
    "transferLocationId": "loc-source-456",
    "change": 5,
    "reason": "API stock transfer",
    "reference": "ERP-TRANSFER-00042"
  }'
```

3. Store both movement IDs from the `201 Created` response.

```json
{
  "removalResult": [
    {
      "stockMovement": {
        "id": "movement-out-123",
        "productId": "product-123",
        "locationId": "loc-source-456",
        "change": -5,
        "reason": "API stock transfer (Transfer Out)",
        "reference": "ERP-TRANSFER-00042",
        "timestamp": "2026-07-20T01:15:00.000Z"
      }
    }
  ],
  "additionResult": {
    "stockMovement": {
      "id": "movement-in-456",
      "productId": "product-123",
      "locationId": "loc-target-789",
      "fromLocationId": "loc-source-456",
      "change": 5,
      "reason": "API stock transfer (Transfer In)",
      "reference": "ERP-TRANSFER-00042",
      "timestamp": "2026-07-20T01:15:01.000Z"
    }
  }
}
```

## Verify the transfer

1. Repeat the inventory request from the pre-transfer check.
2. Confirm the source quantity decreased by five and the destination quantity increased by five.

```json
{
  "items": [
    {
      "id": "loc-source-456",
      "name": "A-01-01",
      "totalQuantity": 45,
      "products": [
        {
          "id": "product-123",
          "quantityOnHand": 45,
          "quantityCommitted": 5,
          "quantityAvailable": 40
        }
      ]
    },
    {
      "id": "loc-target-789",
      "name": "B-02-03",
      "totalQuantity": 15,
      "products": [
        {
          "id": "product-123",
          "quantityOnHand": 15,
          "quantityCommitted": 0,
          "quantityAvailable": 15
        }
      ]
    }
  ],
  "totalCount": 2,
  "page": 1,
  "pageSize": 100,
  "totalPages": 1
}
```

## Retry an uncertain transfer safely

The public WMS API reference does not document an idempotency key for stock movements. Do not automatically repeat a transfer after a timeout.

1. Search movement history with `GET /api/stock-movement?search=ERP-TRANSFER-00042&paginate=true&page=1&limit=50`.
2. Re-read inventory at both locations.
3. Retry only when you have confirmed the first request did not change stock.

Stock movement history returns pagination metadata when you set `paginate=true` or supply `page` or `limit`. `page` starts at `1`, `limit` has a maximum of `1000`, and `hasNext` tells you whether to request another page.

A `400` response means the movement data is invalid. A `403` means the key cannot move stock. A `404` means a product or location ID was not found. For `409`, re-read inventory because the available stock may have changed.

## Related guides

- [Authenticate and look up WMS inventory](/articles/developer-center/starshipit-wms-api/quickstart-authenticate-and-look-up-wms-inventory)
- [WMS stock integrity and adjustments](/articles/starshipit-wms/returns/starshipit-wms-stock-integrity-and-adjustments)
- [WMS API fundamentals](/articles/developer-center/starshipit-wms-api/wms-api-fundamentals)
- [WMS API reference](/developers/api-reference/wms)