# Quickstart: Retrieve and manage WMS jobs
URL: https://support.starshipit.com/articles/14700000001029-quickstart-retrieve-and-manage-wms-jobs
Canonical: https://support.starshipit.com/articles/14700000001029-quickstart-retrieve-and-manage-wms-jobs
Markdown: https://support.starshipit.com/articles/14700000001029-quickstart-retrieve-and-manage-wms-jobs.md
Updated: 2026-07-20

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

> Retrieve paginated WMS jobs, update a job safely, and verify its current state.

Use this quickstart to retrieve ready picking jobs, read one job before changing it, update its priority, and verify the current state.

## Before you begin

- Get the Starshipit API key for the WMS account you want to access.
- Confirm the API key can view jobs and change job assignments or priorities.
- Choose a test job that warehouse staff are not actively processing.
- Replace every example ID below with an ID returned by your WMS account.

## Retrieve a page of jobs

1. Request a bounded page of ready picking jobs.

```bash
curl --request GET \
  --url "https://wms.starshipit.com/api/job?status=READY&type=PICK&page=1&limit=25&sortBy=createdAt&sortDirection=asc" \
  --header "starshipit-api-key: YOUR_STARSHIPIT_API_KEY"
```

2. Store the job `id` and pagination fields.

```json
{
  "success": true,
  "jobs": [
    {
      "id": "job-abc123",
      "type": "PICK",
      "status": "READY",
      "priority": 4,
      "displayName": "Pick SO-1001",
      "assignedUserId": null,
      "packingLocationId": "loc-pack-1",
      "createdAt": "2026-07-20T01:45:00.000Z"
    }
  ],
  "totalCount": 42,
  "totalPages": 2,
  "currentPage": 1,
  "limit": 25
}
```

`jobId` is the job `id`, not its display name or related order number.

Jobs use a 1-based `page` and a `limit` with a maximum of `100`. Process the current page, increment `page`, and stop after `currentPage` reaches `totalPages`.

## Read the job before changing it

1. Retrieve the job by ID immediately before you make a change.

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

2. Confirm the job is still in a state your workflow can manage.

```json
{
  "success": true,
  "job": {
    "id": "job-abc123",
    "type": "PICK",
    "status": "READY",
    "priority": 4,
    "assignedUserId": null,
    "displayName": "Pick SO-1001"
  }
}
```

## Update and verify the job

1. Send only the field you intend to change. Priority must be a whole number from `0` to `10`.

```bash
curl --request PATCH \
  --url https://wms.starshipit.com/api/job/job-abc123 \
  --header "starshipit-api-key: YOUR_STARSHIPIT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "priority": 7
  }'
```

2. Confirm the update response.

```json
{
  "success": true,
  "job": {
    "id": "job-abc123",
    "status": "READY",
    "assignedUserId": null,
    "priority": 7
  }
}
```

3. Repeat `GET /api/job/job-abc123` and confirm the new priority.

```json
{
  "success": true,
  "job": {
    "id": "job-abc123",
    "type": "PICK",
    "status": "READY",
    "priority": 7,
    "assignedUserId": null,
    "displayName": "Pick SO-1001"
  }
}
```

Use the dedicated public pause and resume endpoints for paused-state transitions. Do not set `status` to `PAUSED`, or resume a paused job, through `PATCH /api/job/[id]`. See the [Jobs endpoints](/developers/api-reference/wms#jobs) for assignment, pause, resume, allocation, and expanded job-detail operations.

## Handle retries and conflicts

If an update times out, retrieve the job before retrying. Skip the retry when the job already has the requested value.

| Response | What to do |
| --- | --- |
| `400` | Correct the status, priority, assignment value, or request body. |
| `403` | Confirm the account and permission for the requested job operation. |
| `404` | Confirm the `jobId` and WMS account. |
| `409` | Re-read the job because its status or assignment changed. Skip it or send it for manual review. |
| `429` | Queue the request and retry later with exponential backoff and jitter. |
| `5xx` or timeout | Re-read the job before deciding whether to retry the update. |

The public WMS API reference does not document a general idempotency key for job writes. Compare current state with your intended state before every retry.

## Related guides

- [WMS mobile jobs](/articles/starshipit-wms/mobile-app/starshipit-wms-mobile-jobs)
- [WMS API fundamentals](/articles/developer-center/starshipit-wms-api/wms-api-fundamentals)
- [WMS API reference guide](/articles/developer-center/starshipit-wms-api/wms-api-reference-guide)
- [WMS API reference](/developers/api-reference/wms)