# 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-10-26

> 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.
- Ask your administrator to confirm `jobs.view` permission for reading jobs and `jobs.assign` permission for changing priority.
- 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"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "totalCount": 42,
    "totalPages": 2,
    "hasNext": true,
    "hasPrev": false
  }
}
```

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

Job lists always return a bounded page and pagination metadata. If you omit `page` and `limit`, the defaults are page `1` and `50` jobs. The legacy `paginate=false` parameter does not return all jobs.

Jobs use a 1-based `pagination.page` and a `pagination.limit` with a maximum of `100`. Process the current page, increment the `page` query parameter while `pagination.hasNext` is `true`, and stop when it becomes `false`. You can also compare `pagination.page` with `pagination.totalPages`.

For a compact job list, add `view=summary`. Each row includes whole-job counts in `listSummary` and previews capped at three entries, so use the job-detail endpoint for complete work details. In summary mode, add `exactReference` to find an exact job or order reference across the full job membership before pagination; it takes precedence over `search`. See the [Jobs endpoint](/developers/api-reference/wms#get-api-job-get-jobs) for the summary fields and supported references.

## 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"
  }
}
```

For picking and packing work, use the dedicated workflow endpoints to start and progress the job. These operations resolve the worker from authentication and enforce job ownership; sending a different `performedBy` value does not let you act as another worker. Direct administrative status changes for PICK and PACK jobs require both `jobs.complete` and `jobs.assign`. Closing these jobs with `status: FAILED` also requires `fulfillment.manage` because it attempts to return related orders to pending.

Kitting, replenishment, and putaway actions also use the authenticated worker and enforce their endpoint's claim and assignment requirements. API-key requests do not inherit the administrative recovery access available in an authenticated WMS web session. Read the current job and the endpoint's ownership rules before starting, combining, processing, or cancelling work.

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 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. |
| `404` | Confirm the `jobId` and WMS account. |
| `409` | Re-read the job because its status or assignment changed. For `JOB_NOT_CLAIMED`, claim the job through the appropriate workflow before continuing. For `JOB_ALREADY_CLAIMED`, refresh and leave the job with its assigned worker or ask a manager to reassign it. |
| `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)