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

# Subscription Orders

> Poll the current status of a subscription and its orders

## Get Subscription Orders

Returns the subscription's current state and every order under it, including each order's ID, state, pickup date, pickup window, and the time of its last state change. Use it to track order progress after activation. It is also how you discover the order IDs that belong to a subscription.

```http theme={null}
GET /external-partner/subscription/{subscription_id}/orders
```

**Headers**

| Header            | Value                |
| ----------------- | -------------------- |
| `API-KEY`         | Your partner API key |
| `Accept-Language` | `ar` or `en`         |

<Note>
  No customer token is required. This endpoint is server-to-server, so your backend can call it with just your API key. It is a `GET` request, so no `Idempotency-Key` is needed.
</Note>

**Path Parameters**

| Param             | Required | Notes                                                                |
| ----------------- | -------- | -------------------------------------------------------------------- |
| `subscription_id` | ✅        | From the [Subscribe](/api-reference/subscription#subscribe) response |

**Response**

```json theme={null}
{
  "success": true,
  "message": "resource fetched successfully.",
  "data": {
    "subscription": {
      "id": 4512,
      "state": "active",
      "orders_count": 4,
      "start_date": "2026-07-06",
      "end_date": "2026-08-09"
    },
    "orders": [
      {
        "id": 18734,
        "state": "delivered",
        "pickup_date": "2026-07-07",
        "pickup_period": { "code": "evening", "time_range": "4 PM - 10 PM" },
        "state_changed_at": "2026-07-08T14:22:31+03:00",
        "cancelled_at": null
      },
      {
        "id": 18735,
        "state": "scheduled",
        "pickup_date": "2026-07-14",
        "pickup_period": { "code": "evening", "time_range": "4 PM - 10 PM" },
        "state_changed_at": null,
        "cancelled_at": null
      }
    ]
  },
  "status_code": 200
}
```

Orders are sorted by `pickup_date`, earliest first. Timestamps are ISO 8601 in Riyadh time (`+03:00`). `state_changed_at` is `null` while an order is still in its initial `scheduled` state. `cancelled_at` is set only when an order was cancelled.

***

## Subscription States

| State       | Meaning                                                                                               |
| ----------- | ----------------------------------------------------------------------------------------------------- |
| `draft`     | Created, payment not yet confirmed via [Confirm Payment](/api-reference/subscription#confirm-payment) |
| `active`    | Paid, and at least one order is still in progress                                                     |
| `completed` | All orders reached a final state (delivered or cancelled)                                             |
| `cancelled` | Subscription and all its orders were cancelled and refunded                                           |

## Order States

| State                     | Meaning                                                             |
| ------------------------- | ------------------------------------------------------------------- |
| `scheduled`               | Scheduled for a future date, not yet processed                      |
| `picked_up_from_customer` | Our driver picked up the laundry bags from the customer             |
| `received_in_laundry`     | The bags were dropped off at our facility                           |
| `out_for_delivery`        | Clean laundry is on its way back to the customer                    |
| `delivered`               | Successfully delivered to the customer. Final state                 |
| `cancelled`               | Cancelled and refunded. Only possible from `scheduled`. Final state |

***

## Errors

**Not found (404)**: the subscription ID does not exist, or it does not belong to your integration:

```json theme={null}
{
  "success": false,
  "message": "You do not have access to this subscription"
}
```

| Status | When                                                          |
| ------ | ------------------------------------------------------------- |
| `401`  | `API-KEY` header missing                                      |
| `403`  | API key invalid, expired, or inactive                         |
| `404`  | Unknown subscription, or not created through your integration |
| `429`  | Too many requests. Slow down and retry later                  |

***

## Polling Guidance

* States are effectively real-time: responses are briefly cached, but the cache is refreshed the moment an order changes state.
* Poll every **5 to 15 minutes** during service hours. Polling more often than every 5 minutes per subscription brings no benefit.
* Only poll subscriptions that are not yet final. Stop polling once the subscription is `completed` or `cancelled`, or when all of its orders are `delivered` or `cancelled`.