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

# Order Lifecycle

> Understanding order status transitions in RxScale

# Order Lifecycle

Every order in RxScale moves through a series of statuses as it progresses from creation to completion. Understanding these statuses is essential for building a reliable integration.

## Status Flow

```
  init
     |
     v
waiting for pharmacy -----> cancelled
     |
     v
 pending review ----------> cancelled
     |
     v
 in-progress
     |
     v
ready_for_pickup
     |
     v
 completed
```

## Status Descriptions

| Status                 | Description                                                                | Who sets it                      |
| ---------------------- | -------------------------------------------------------------------------- | -------------------------------- |
| `init`                 | Order has been created in the system but is not yet assigned to a pharmacy | System                           |
| `waiting for pharmacy` | Order is assigned to a pharmacy and ready to be processed                  | System                           |
| `pending review`       | Pharmacy is reviewing the order and checking availability                  | Pharmacy (via API)               |
| `in-progress`          | Pharmacy has started preparation                                           | Pharmacy (via API)               |
| `ready_for_pickup`     | Order is packed and ready for pickup or shipping                           | Pharmacy (via API)               |
| `completed`            | Order has been delivered and finalized (includes stock reduction)          | Pharmacy (via complete endpoint) |
| `cancelled`            | Order was cancelled before completion                                      | System or Pharmacy               |

## Transitions

### Waiting for Pharmacy to Pending Review

When your pharmacy receives a new order (status: `waiting for pharmacy`), acknowledge that review has started:

```bash theme={null}
curl -X PATCH "https://api.rxscale.com/v1/external_pharmacy_api/pharmacy_orders/po-abc123/status" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"status": "pending review"}'
```

### Pending Review to In Progress

Once stock availability is confirmed and preparation begins, update the status to `in-progress`:

```bash theme={null}
curl -X PATCH "https://api.rxscale.com/v1/external_pharmacy_api/pharmacy_orders/po-abc123/status" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"status": "in-progress"}'
```

### In Progress to Ready for Pickup

Once the order has been packed and is ready for pickup or shipping, update the status to `ready_for_pickup`:

```bash theme={null}
curl -X PATCH "https://api.rxscale.com/v1/external_pharmacy_api/pharmacy_orders/po-abc123/status" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"status": "ready_for_pickup"}'
```

### Ready for Pickup to Completed

When the order has been delivered or otherwise fulfilled, complete it through the dedicated complete order endpoint. This step includes stock reduction and order finalization.

```bash theme={null}
curl -X PATCH "https://api.rxscale.com/v1/external_pharmacy_api/pharmacy_orders/po-abc123/complete_order" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_links": [
      {
        "tracking_link": "https://tracking.example.com/parcel/123",
        "carrier": "DHL"
      }
    ]
  }'
```

<Note>
  Do not set `completed` through the generic status endpoint. Use `complete_order` so RxScale can reduce stock and emit shipment and order update events consistently.
</Note>

### Cancellation

An order can be cancelled before completion:

```bash theme={null}
curl -X PATCH "https://api.rxscale.com/v1/external_pharmacy_api/pharmacy_orders/po-abc123/status" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"status": "cancelled"}'
```

## Webhook Notifications

You will receive webhook notifications for status changes if you have subscribed to the `pharmacy_order_updated` event type. Each notification includes the full order data with the new status.

See [Webhook Events](/webhooks/events) for payload details.

## Best Practices

<AccordionGroup>
  <Accordion title="Process orders promptly">
    Move orders from `waiting for pharmacy` to `pending review` as soon as your team begins reviewing them. This provides visibility to all stakeholders.
  </Accordion>

  <Accordion title="Update status at each step">
    Keep the status current. Accurate status tracking helps with customer communication, reporting, and issue resolution.
  </Accordion>

  <Accordion title="Handle cancellations gracefully">
    Listen for `pharmacy_order_updated` webhooks with `cancelled` status. If a cancellation arrives while you are preparing an order, stop processing and update your internal systems accordingly.
  </Accordion>

  <Accordion title="Do not skip statuses">
    Always follow the order: `waiting for pharmacy` to `pending review` to `in-progress` to `ready_for_pickup`. Use `complete_order` only when the order is fulfilled.
  </Accordion>
</AccordionGroup>