Subscription 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.

GET /external-partner/subscription/{subscription_id}/orders

Headers

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

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.

Path Parameters

Param	Required	Notes
`subscription_id`	✅	From the Subscribe response

Response

{
  "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
`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:

{
  "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.

Getting Started

API Reference

Get Subscription Orders

Subscription States

Order States

Errors

Polling Guidance

​Get Subscription Orders

​Subscription States

​Order States

​Errors

​Polling Guidance

Get Subscription Orders

Subscription States

Order States

Errors

Polling Guidance