---
title: "Get a bulk order job"
description: "Check the status of a bulk-order job, with each order's result."
url: https://docs.stoqapp.com/v2-reference/preorders-orders/get-a-bulk-order-job/
api: "API v2 reference"
method: GET
path: "/preorders/orders/jobs/{job_id}"
---

# Get a bulk order job

`GET https://app.stoqapp.com/api/v2/external/preorders/orders/jobs/{job_id}`

Check the status of a bulk-order job, with each order's result.

**Note:** status is queued, running, completed or failed. succeeded / failed list each finished order by id and shopify_order_id; failed entries carry the reason. state adds stalled: nothing moved for stall_after_seconds (stalled_reason not_started or no_progress); created_at, started_at, last_progress_at and finished_at are UTC. Results are kept for 24 hours.

## Path parameters

- `job_id` (string, required): The job ID a bulk order call returned.

## Returns

- `job_id` (string): Id of the background job doing the work.
- `operation` (string): The bulk action the job runs. One of: `release`, `send_confirmation`, `send_shipping_update`, `open_scheduled_fulfillments`, `reschedule_fulfillment`, `reschedule_payment`, `collect_payment`, `hold_fulfillments`, `split_fulfillment_orders`.
- `status` (string): Where the job is: queued, running, completed, failed or cancelled; unknown if its progress can't be read. One of: `queued`, `running`, `completed`, `failed`, `cancelled`, `unknown`.
- `total` (integer): How many orders the job acts on.
- `processed` (integer): How many orders it has worked through so far.
- `succeeded_count` (integer): How many orders the action succeeded on.
- `failed_count` (integer): How many orders the action failed on.
- `succeeded` (array of objects): The orders the action succeeded on.
  - `id` (string): STOQ's id for the order.
  - `shopify_order_id` (string): The Shopify order gid (gid://shopify/Order/&lt;id&gt;).
  - `name` (string): The Shopify order name, such as #1001.
- `failed` (array of objects): The orders the action failed on, each with the reason.
  - `id` (string): STOQ's id for the order.
  - `shopify_order_id` (string): The Shopify order gid (gid://shopify/Order/&lt;id&gt;).
  - `name` (string): The Shopify order name, such as #1001.
  - `error` (string): Why the action failed for this order.
- `state` (string): status, with stalled added: nothing has moved for stall_after_seconds. One of: `queued`, `running`, `stalled`, `failed`, `completed`, `cancelled`.
- `stalled_reason` (null): Why the job is stalled: not_started (no worker picked it up) or no_progress (it started, then stopped). Null unless state is stalled.
- `created_at` (string): When the job was submitted (ISO 8601, UTC).
- `started_at` (null): When a worker started the job (ISO 8601, UTC), or null before then.
- `last_progress_at` (null): When the job last moved (ISO 8601, UTC), or null before it started.
- `finished_at` (string, nullable): When the job finished (ISO 8601, UTC), or null while it runs.
- `stall_after_seconds` (integer): Seconds without progress after which state turns stalled.

Rate limit: this call costs 1 point ([rate limits](https://docs.stoqapp.com/docs/rate-limits/)).

## Example request

```sh
curl "https://app.stoqapp.com/api/v2/external/preorders/orders/jobs/{job_id}" \
  -H "X-Auth-Token: $STOQ_API_KEY"
```

## 200

Accepted: the work was queued as a job. Poll `status_url` until it finishes.

```json
{
  "job_id": "string",
  "operation": "release",
  "status": "queued",
  "total": 1,
  "processed": 1,
  "succeeded_count": 1,
  "failed_count": 1,
  "succeeded": [
    {
      "id": "string",
      "shopify_order_id": "string",
      "name": "string"
    }
  ],
  "failed": [
    {
      "id": "string",
      "shopify_order_id": "string",
      "name": "string",
      "error": "string"
    }
  ],
  "state": "queued",
  "stalled_reason": null,
  "created_at": "2026-01-15T09:30:00Z",
  "started_at": null,
  "last_progress_at": null,
  "finished_at": "string",
  "stall_after_seconds": 1
}
```

## 401

Missing or invalid `X-Auth-Token`.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "auth_invalid",
  "details": [
    {
      "code": "auth_invalid",
      "message": "Invalid API key",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 404

The resource does not exist for this shop, or the action path is not registered.

```json
{
  "errors": [
    "Offer not found"
  ],
  "code": "not_found",
  "details": [
    {
      "code": "not_found",
      "message": "Offer not found",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 422

The request failed validation.

```json
{
  "errors": [
    "name is required"
  ],
  "code": "validation_failed",
  "details": [
    {
      "code": "validation_failed",
      "message": "name is required",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

## 429

Rate limited: cost-weighted per token (read 1, write 2; 360 points / 60s). Check `Retry-After`.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited",
  "details": [
    {
      "code": "rate_limited",
      "message": "Rate limit exceeded",
      "path": null,
      "value": null,
      "expected": null
    }
  ]
}
```

