> ## 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

> Get available days, create a subscription, and confirm payment

## Available Days

Returns which days and periods are available for pickup, based on the number of orders in the selected plan.

```http theme={null}
GET /external-partner/subscription/available-days?orders_count={n}
```

**Headers**

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

**Query Parameters**

| Param          | Required | Notes                                                       |
| -------------- | -------- | ----------------------------------------------------------- |
| `orders_count` | ✅        | Use `plan_types[].orders_count` from the selected plan type |

**Response**

```json theme={null}
{
  "success": true,
  "data": [
    {
      "day_name": "Wednesday",
      "week_day": 3,
      "date": "2025-10-29",
      "is_today": false,
      "periods": [
        { "code": "morning", "name": "Morning", "period": "9 AM - 3 PM" },
        { "code": "evening", "name": "Evening", "period": "4 PM - 10 PM" }
      ]
    }
  ],
  "status_code": 200
}
```

**Error — Location not covered (400)**

```json theme={null}
{
  "success": false,
  "message": "Sorry but we don't cover your area yet"
}
```

***

## Subscribe

Creates a subscription in `draft` state. The customer's pickup schedule is set here.

```http theme={null}
POST /external-partner/subscription/subscribe
```

**Headers**

| Header            | Value                     |
| ----------------- | ------------------------- |
| `Authorization`   | `Bearer {customer_token}` |
| `Idempotency-Key` | Unique UUID               |

**Query Parameters** *(passed in URL, not body)*

| Param                     | Required | Notes                                  |
| ------------------------- | -------- | -------------------------------------- |
| `plan_id`                 | ✅        | From List Plans                        |
| `plan_type_id`            | ✅        | From List Plans → plan\_types          |
| `preferred_pickup_day`    | ✅\*      | Day of week: `monday`, `tuesday`, etc. |
| `preferred_pickup_date`   | ✅\*      | Specific date: `YYYY-MM-DD`            |
| `preferred_pickup_period` | ✅        | `morning` or `evening`                 |

\*Either `preferred_pickup_day` or `preferred_pickup_date` is required, not both.

**Response**

```json theme={null}
{
  "success": true,
  "data": {
    "id": 5355,
    "total": 799,
    "orders_count": 4,
    "start_date": "2025-10-29T00:00:00.000000Z",
    "end_date": "2025-12-11T23:59:59.000000Z",
    "preferred_pickup_day": { "code": "monday", "name": "Monday" },
    "preferred_pickup_period": { "code": "evening", "name": "Evening", "period": "4 PM - 10 PM" },
    "state": { "code": "draft", "name": "Draft" }
  },
  "status_code": 200
}
```

<Note>
  The subscription is in `draft` — no pickups are scheduled until payment is confirmed.
</Note>

***

## Confirm Payment

Marks the subscription as paid and activates it. Call this after your payment flow completes.

```http theme={null}
POST /external-partner/subscription/confirm-payment
```

**Headers**

| Header            | Value                     |
| ----------------- | ------------------------- |
| `Authorization`   | `Bearer {customer_token}` |
| `Idempotency-Key` | Unique UUID               |

**Body** `multipart/form-data`

| Field             | Type    | Required | Notes                                        |
| ----------------- | ------- | -------- | -------------------------------------------- |
| `subscription_id` | integer | ✅        | From Subscribe response                      |
| `reference_id`    | string  | ❌        | Your payment gateway's transaction reference |

**Response**

```json theme={null}
{
  "success": true,
  "data": {
    "subscription": {
      "id": 5360,
      "total": 799,
      "orders_count": 4,
      "state": { "code": "active", "name": "Active" }
    },
    "invoice_url": "https://..."
  },
  "status_code": 200
}
```

**Error — Already active (400)**

```json theme={null}
{
  "success": false,
  "message": "This subscription is already active"
}
```