> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Update order status

> Report fulfillment and order progress from your POS back to Fire spark.

Updates the operational status of an order after your POS or RMS processes it. Call this endpoint when the kitchen marks an order as preparing, ready, delivered, or cancelled so connected channels reflect the same progress.

<Note>
  Requires an access token with the `orders:write` scope. See
  [Token](/docs/integrations-api/oauth/token/post) to obtain a token.
</Note>

## When to call this endpoint

| POS event                       | Suggested Fire spark update                          |
| ------------------------------- | ---------------------------------------------------- |
| Ticket accepted in kitchen      | `fulfillment_status: PREPARING`                      |
| Order bagged / ready for pickup | `fulfillment_status: PREPARED`                       |
| Driver dispatched               | `fulfillment_status: DELIVERING`                     |
| Handed to customer              | `fulfillment_status: DELIVERED`, `status: COMPLETED` |
| Voided in POS                   | `status: CANCELLED`, `fulfillment_status: CANCELLED` |

Fire spark propagates these updates to channels and may emit `order.updated` webhooks to other integrations listening on the merchant.

## Path parameters

| Parameter | Required | Description                                                                             |
| --------- | -------- | --------------------------------------------------------------------------------------- |
| `id`      | Yes      | External order identifier. Alphanumeric characters, `_`, and `-` only. 1–64 characters. |

## Request body

| Field    | Required | Type   | Description                              |
| -------- | -------- | ------ | ---------------------------------------- |
| `status` | Yes      | string | Target order status in your POS workflow |

```bash theme={null}
curl -X PATCH "https://firespark.cloud/api/integrations/v1/orders/ord-48291/status" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "COMPLETED"
  }'
```

## Response

Returns the updated order in `data`.

<ResponseExample>
  ```json Success theme={null}
  {
    "data": {
      "id": "ord-48291",
      "status": "COMPLETED",
      "fulfillment_status": "DELIVERED",
      "payment_status": "PAID"
    }
  }
  ```
</ResponseExample>

<Info>
  Pair this endpoint with [`order.injected`](/docs/integrations-api/orders/webhooks):
  the webhook delivers the order into your POS; this endpoint keeps Fire spark
  in sync as the ticket moves through your operational workflow.
</Info>

## Error responses

| Status | Description                                     |
| ------ | ----------------------------------------------- |
| `401`  | Missing or invalid access token                 |
| `403`  | Token does not include the `orders:write` scope |
| `404`  | No order exists for this id                     |
| `422`  | Invalid status transition                       |


## OpenAPI

````yaml PATCH /orders/{id}/status
openapi: 3.0.1
info:
  title: Fire spark Integrations API
  description: POS and RMS integration endpoints for Fire spark.
  version: 1.0.0
servers:
  - url: https://firespark.cloud/api/integrations/v1
security:
  - bearerAuth: []
paths:
  /orders/{id}/status:
    patch:
      summary: Update order status
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 64
            pattern: ^[a-zA-Z0-9_-]+$
          description: External order identifier.
      requestBody:
        required: true
        description: New order status.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderStatusPatchBody'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    additionalProperties: true
components:
  schemas:
    OrderStatusPatchBody:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          description: Target order status in your POS or RMS workflow.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````