---
feature: Prepaid packages and sessions
slug: my-packages
surface: client
consumer: flutter
version: 1.1.0
status: ready
brd_version: "1.3"
brd_ids: [CUST-008, CUST-013, CUST-015, CUST-020]
business_rules: [BR-02, BR-07, BR-08, BR-13, BR-14, BR-20, BR-24, BR-26, BR-28]
decisions: [D1, DEC-01, DEC-09, TD-123, TD-124, TD-125, TD-126, TD-127, TD-128]
schema_tables: [packages, package_items, customer_packages, customer_package_items, orders, order_items, payments]
screens: [customer--packages--02-details-p2*]
related_docs: [catalog.md, booking.md, orders.md, cancellation.md, ../provider/orders.md, ../admin/orders.md]
last_updated: 2026-11-03
---

# Prepaid packages and sessions — Flutter Integration Guide (client)

> **Base URL:** `{HOST}/api/v1/client`. Shared authentication, envelopes and errors: [API conventions](../API_CONVENTIONS.md).

## Version history

| Version | Date | Type | Summary | App action required |
|---------|------|------|---------|---------------------|
| 1.1.0 | 2026-11-03 | MINOR | Package purchases accept full wallet payment. | Offer wallet when enabled and handle the wallet payment errors. |
| 1.0.1 | 2026-10-27 | PATCH | Document the inactive package slots error. | None |
| 1.0.0 | 2026-10-27 | Initial | Purchase, owned packages and session booking. | Follow the flow and capability flags below. |

## Changelog

### 1.1.0 — 2026-11-03

- **Added:** Package purchases accept full wallet payment.
- **Breaking:** No. **App action required:** Offer wallet when enabled and handle the wallet payment errors.
- **BRD / decisions:** CUST-015/016, TD-164.

### 1.0.1 — 2026-10-27

- **Fixed:** Document the inactive package slots error.
- **Breaking:** No. **App action required:** None.


### 1.0.0 — 2026-10-27

- **Added:** Purchase, package list and details, session slots, quote and creation.
- **Changed / fixed / removed:** None.
- **Breaking:** No.
- **Endpoints affected:** purchase, my-packages, session slots/quote/store and existing payment/cancellation.
- **App action required:** Follow the flow and capability flags below.
- **BRD / decisions:** D1, CUST-008/013/015/020, TD-123–128.

## 1. Business summary

A customer buys a prepaid package once, then books each included session as a scheduled visit. Buying does not require provider acceptance; a session does. Package and service snapshots preserve the purchased terms.

## 2. User flow and screens

| Step | Endpoint | App behavior |
|------|----------|--------------|
| Package details | `GET /packages/{package}` | Display Buy only when `can_buy` is true; sign in first. |
| Purchase | `POST /packages/{package}/purchase` | Save order and customer package UUIDs; pay the order. |
| Payment | `POST /orders/{order}/pay` | A successful purchase is completed and activates the package. Failure remains retryable before the deadline. |
| My packages | `GET /my-packages` and `GET /my-packages/{customerPackage}` | Show status, expiry and remaining sessions; use `can_book_session`. |
| Book a visit | slots → quote → `POST /my-packages/{customerPackage}/sessions` | Choose owned item, address and start. Creation holds one session and awaits provider acceptance. |
| Pay delivery | `POST /orders/{order}/pay` | After acceptance, pay a positive delivery charge. A zero-total session is marked paid on acceptance without a payment row. |

## 3. Endpoints

All routes below require a customer bearer token. IDs are UUIDs. Create requests require a nonempty `Idempotency-Key` of at most 100 characters; repeat the same key and payload to replay, and use a new key for a different request.

| Method and path | Input | Result |
|-----------------|-------|--------|
| `POST /packages/{package}/purchase` | `Idempotency-Key`; no body | 201 order in `awaiting_payment`, with `customer_package_id`; no visit address. |
| `GET /my-packages` | Optional `tab=active\|finished`, `page` ≥ 1, `per_page` 1–100 | Paginated own packages. Omit tab to include pending payment. |
| `GET /my-packages/{customerPackage}` | Owned package UUID | Purchase snapshot and service balances; another customer's UUID returns 404. |
| `GET /my-packages/{customerPackage}/sessions/slots` | Required `customer_package_item_id`, `address_id`, `date` (`YYYY-MM-DD`, Saudi local) | Available starts using the purchased duration and expiry. |
| `POST /my-packages/{customerPackage}/sessions/quote` | Required `customer_package_item_id`, `address_id`, `scheduled_at` | Prepaid service is zero; delivery may be charged. |
| `POST /my-packages/{customerPackage}/sessions` | Same fields as quote, optional `notes_to_provider` ≤ 1000, `Idempotency-Key` | 201 scheduled session in `pending_provider`. |
| `POST /orders/{order}/pay` | Payment method per [booking](booking.md) | Pay purchase or accepted session. |
| `POST /orders/{order}/cancel` | Optional reason per [cancellation](cancellation.md) | Unpaid purchase cancels; paid purchase refund is deferred. Session cancellation releases the held session. |

### Recorded success responses

Postman: `client.my-packages.index` › "200 Owned packages".

```json
{
    "status": "success",
    "message": "",
    "data": {
        "current_page": 1,
        "data": [
            {
                "id": "01a17cd9-1b5d-731a-810c-3363eb46ed7e",
                "name": "Sample-nwbw17124987",
                "status": {
                    "value": "pending_payment",
                    "label": "Pending payment"
                },
                "provider": {
                    "id": "01a17cd9-1b18-7384-9980-f97230ba9337",
                    "name": "Ms. Rita Kautzer"
                },
                "price_paid": "100.00",
                "validity_days": 45,
                "activated_at": null,
                "expires_at": null,
                "sessions_remaining": 3,
                "can_book_session": false
            }
        ],
        "first_page_url": "http://localhost/api/v1/client/my-packages?page=1",
        "from": 1,
        "last_page": 1,
        "last_page_url": "http://localhost/api/v1/client/my-packages?page=1",
        "links": [
            {
                "url": null,
                "label": "&laquo; Previous",
                "page": null,
                "active": false
            },
            {
                "url": "http://localhost/api/v1/client/my-packages?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next &raquo;",
                "page": null,
                "active": false
            }
        ],
        "next_page_url": null,
        "path": "http://localhost/api/v1/client/my-packages",
        "per_page": 15,
        "prev_page_url": null,
        "to": 1,
        "total": 1
    }
}
```

Postman: `client.packages.purchase` › "201 Package purchase created".

```json
{
    "status": "success",
    "message": "",
    "data": {
        "id": "01a17cd9-1a77-7321-8229-2f1c04d655e9",
        "code": "JSH-360008",
        "status": {
            "value": "awaiting_payment",
            "label": "Awaiting payment"
        },
        "payment_status": {
            "value": "unpaid",
            "label": "Unpaid"
        },
        "booking_type": {
            "value": "scheduled",
            "label": "Scheduled"
        },
        "source": {
            "value": "package",
            "label": "Package"
        },
        "finder_search_id": null,
        "provider": {
            "id": "01a17cd9-182e-7080-a32f-02da5372c51e",
            "name": "Lessie Kovacek"
        },
        "scheduled_at": null,
        "eta_minutes": null,
        "estimated_duration_min": null,
        "address": {
            "text": null,
            "lat": null,
            "lng": null
        },
        "services": [
            {
                "id": "01a17cd9-1a7c-72c8-8201-46bc8c2d0e19",
                "name": "Sample-czop64131296",
                "duration_min": null,
                "unit_price": "100.00",
                "options_price": "0.00",
                "line_total": "100.00",
                "options": []
            }
        ],
        "services_amount": "0.00",
        "package_amount": "100.00",
        "delivery_fee": "0.00",
        "discount_amount": "0.00",
        "vat_amount": "0.00",
        "total_amount": "100.00",
        "can_pay": true,
        "payment_due_at": "2026-10-25T07:15:00+00:00",
        "can_cancel": true,
        "can_chat": false,
        "can_rate": false,
        "respond_before": null,
        "rejection_reason": null,
        "can_choose_another_time": false,
        "can_choose_another_provider": false,
        "timeline": [
            {
                "status": {
                    "value": "awaiting_payment",
                    "label": "Awaiting payment"
                },
                "at": "2026-10-27T10:12:45+00:00"
            }
        ],
        "delay_alert": null,
        "refund": null,
        "cancellation": {
            "reason": null,
            "at": null,
            "fee": "0.00",
            "rule_id": null
        },
        "created_at": "2026-10-25T07:00:00+00:00",
        "customer_package_id": "01a17cd9-1a7f-7113-a64f-b8e7a265a5ea"
    }
}
```

Postman: `client.my-packages.show` › "200 Owned package details".

```json
{
    "status": "success",
    "message": "",
    "data": {
        "id": "01a17cd9-1b5d-731a-810c-3363eb46ed7e",
        "name": "Sample-nwbw17124987",
        "status": {
            "value": "active",
            "label": "Active"
        },
        "provider": {
            "id": "01a17cd9-1b18-7384-9980-f97230ba9337",
            "name": "Ms. Rita Kautzer"
        },
        "price_paid": "100.00",
        "validity_days": 45,
        "activated_at": "2026-10-25T07:00:00+00:00",
        "expires_at": "2026-12-09T07:00:00+00:00",
        "sessions_remaining": 3,
        "can_book_session": true,
        "purchase_order_id": "01a17cd9-1b59-7205-8dc2-ffbd112791be",
        "services": [
            {
                "id": "01a17cd9-1b5f-7058-9302-a8c8ed5c7369",
                "service_id": "01a17cd9-1b26-7289-bf54-a37305977b8d",
                "name": "مكياج",
                "duration_min": 75,
                "sessions_total": 3,
                "sessions_used": 0,
                "sessions_remaining": 3,
                "can_book_session": true,
                "booking_unavailable_reason": null
            }
        ]
    }
}
```

Postman: `client.my-packages.sessions.slots` › "200 Available session slots".

```json
{
    "status": "success",
    "message": "",
    "data": {
        "date": "2026-10-28",
        "provider_id": "01a17cd9-21e7-7052-b2d6-2b8206c2e43b",
        "service_id": "01a17cd9-21f2-7087-865a-7f2557eae011",
        "slots": [
            "2026-10-28T09:00:00+03:00",
            "2026-10-28T09:15:00+03:00",
            "2026-10-28T09:30:00+03:00"
        ]
    }
}
```

Postman: `client.my-packages.sessions.quote` › "200 Prepaid session quote".

```json
{
    "status": "success",
    "message": "",
    "data": {
        "provider": {
            "id": "01a17cd9-21e7-7052-b2d6-2b8206c2e43b",
            "name": "Mr. Abelardo Fadel MD"
        },
        "address": {
            "id": "01a17cd9-21e5-7026-9530-af0d8d81cfc8",
            "text": "jftaefsgyclw"
        },
        "booking_type": {
            "value": "scheduled",
            "label": "Scheduled"
        },
        "services": [
            {
                "id": "01a17cd9-21f2-7087-865a-7f2557eae011",
                "name": "مكياج",
                "base_price": "0.00",
                "options": [],
                "duration_min": 90,
                "line_total": "0.00"
            }
        ],
        "services_amount": "0.00",
        "delivery_fee": "20.00",
        "discount_amount": "0.00",
        "vat_amount": "0.00",
        "total_amount": "20.00",
        "distance_km": "0.000",
        "eta_minutes": null,
        "scheduled_at": "2026-10-28T06:00:00+00:00",
        "package_amount": "0.00"
    }
}
```

Postman: `client.my-packages.sessions.store` › "201 Session booking created".

```json
{
    "status": "success",
    "message": "",
    "data": {
        "id": "01a17cd9-3480-711e-81df-e1524026b28c",
        "code": "JSH-802293",
        "status": {
            "value": "pending_provider",
            "label": "Waiting for provider"
        },
        "payment_status": {
            "value": "unpaid",
            "label": "Unpaid"
        },
        "booking_type": {
            "value": "scheduled",
            "label": "Scheduled"
        },
        "source": {
            "value": "package",
            "label": "Package"
        },
        "finder_search_id": null,
        "provider": {
            "id": "01a17cd9-31bd-716d-909a-c8e61c52418e",
            "name": "Dr. Robyn Zieme"
        },
        "scheduled_at": "2026-10-28T06:00:00+00:00",
        "eta_minutes": null,
        "estimated_duration_min": 90,
        "address": {
            "text": "hwacntsqnmxn",
            "lat": "24.713552",
            "lng": "46.675296"
        },
        "services": [
            {
                "id": "01a17cd9-3486-738f-b1fe-a776cabcba54",
                "name": "مكياج",
                "duration_min": 90,
                "unit_price": "0.00",
                "options_price": "0.00",
                "line_total": "0.00",
                "options": []
            }
        ],
        "services_amount": "0.00",
        "package_amount": "0.00",
        "delivery_fee": "20.00",
        "discount_amount": "0.00",
        "vat_amount": "0.00",
        "total_amount": "20.00",
        "can_pay": false,
        "payment_due_at": null,
        "can_cancel": true,
        "can_chat": false,
        "can_rate": false,
        "respond_before": "2026-10-27T10:42:51+00:00",
        "rejection_reason": null,
        "can_choose_another_time": false,
        "can_choose_another_provider": false,
        "timeline": [
            {
                "status": {
                    "value": "pending_provider",
                    "label": "Waiting for provider"
                },
                "at": "2026-10-27T10:12:51+00:00"
            }
        ],
        "delay_alert": null,
        "refund": null,
        "cancellation": {
            "reason": null,
            "at": null,
            "fee": "0.00",
            "rule_id": null
        },
        "created_at": "2026-10-27T10:12:51+00:00"
    }
}
```

### Errors and response examples

### Route-by-route error reference

#### `POST /packages/{package}/purchase`

| HTTP | `error_code` | When | App action |
|------|--------------|------|------------|
| 401 | (shared) | No valid customer token | Sign in |
| 403 | (shared) | Wrong app token | Use client token |
| 404 | — | Package UUID unknown | Refresh catalog |
| 409 | `IDEMPOTENCY_KEY_REUSED` | Same key sent for a different package | Use a new key |
| 422 | `VALIDATION_FAILED` | `Idempotency-Key` header missing or > 100 chars | Add/shorten header |
| 422 | `PACKAGE_NOT_BUYABLE` | Package hidden, suspended, service inactive or provider suspended | Refresh catalog |
| 429 | `RATE_LIMITED` | Too many requests per minute | Wait and retry |

Postman: `client.packages.purchase` › "404 Unknown package not found", "409 Purchase key reused for a different package", "422 Package no longer buyable".

#### `GET /my-packages`

| HTTP | `error_code` | When | App action |
|------|--------------|------|------------|
| 401 | (shared) | No valid customer token | Sign in |
| 403 | (shared) | Wrong app token | Use client token |
| 422 | `VALIDATION_FAILED` | `tab` value not in `active\|finished` | Omit or correct tab |

Postman: `client.my-packages.index` › "422 Invalid package tab".

#### `GET /my-packages/{customerPackage}`

| HTTP | `error_code` | When | App action |
|------|--------------|------|------------|
| 401 | (shared) | No valid customer token | Sign in |
| 403 | (shared) | Wrong app token | Use client token |
| 404 | — | Package not owned by the signed-in customer | Refresh list |

Postman: `client.my-packages.show` › "404 Package belongs to another customer".

#### `GET /my-packages/{customerPackage}/sessions/slots`

| HTTP | `error_code` | When | App action |
|------|--------------|------|------------|
| 401 | (shared) | No valid customer token | Sign in |
| 403 | (shared) | Wrong app token | Use client token |
| 404 | — | Package not owned | Refresh list |
| 422 | `VALIDATION_FAILED` | `customer_package_item_id`, `address_id` or `date` missing/invalid | Correct fields |
| 422 | `PACKAGE_NOT_ACTIVE` | Package is not active or has expired | Refresh package details and show its current state |

Postman: `client.my-packages.sessions.slots` › "422 Missing slot fields".

#### `POST /my-packages/{customerPackage}/sessions/quote`

| HTTP | `error_code` | When | App action |
|------|--------------|------|------------|
| 401 | (shared) | No valid customer token | Sign in |
| 403 | (shared) | Wrong app token | Use client token |
| 404 | — | Package not owned | Refresh list |
| 422 | `VALIDATION_FAILED` | Required fields missing or invalid | Correct fields |
| 422 | `PACKAGE_NOT_ACTIVE` | Package status is not `active`, or `expires_at` is in the past | Refresh details; show expired state |
| 422 | `PACKAGE_SESSION_UNAVAILABLE` | All sessions used (`reason: no_sessions_left`), or the service (`service_unavailable`) or provider (`provider_unavailable`) is no longer available | Inspect `data.reason`; offer to contact support |
| 422 | `PACKAGE_SESSION_AFTER_EXPIRY` | `scheduled_at` is after the package expiry | Choose an earlier start |

Postman: `client.my-packages.sessions.quote` › "404 Foreign package not found on quote", "422 Package has expired", "422 No sessions remain", "422 Package service unavailable", "422 Package provider unavailable", "422 Session starts after package expiry".

#### `POST /my-packages/{customerPackage}/sessions`

| HTTP | `error_code` | When | App action |
|------|--------------|------|------------|
| 401 | (shared) | No valid customer token | Sign in |
| 403 | (shared) | Wrong app token | Use client token |
| 404 | — | Package not owned | Refresh list |
| 409 | `IDEMPOTENCY_KEY_REUSED` | Key reused with a different payload | Use a new key |
| 422 | `VALIDATION_FAILED` | Required fields or idempotency header invalid | Correct and retry |
| 422 | `PACKAGE_NOT_ACTIVE` | Package not active or expired | Refresh details |
| 422 | `PACKAGE_SESSION_UNAVAILABLE` | No sessions remain (`no_sessions_left`) | Show consumed state |
| 422 | `PACKAGE_SESSION_AFTER_EXPIRY` | `scheduled_at` after expiry | Choose an earlier start |
| 429 | `RATE_LIMITED` | Too many bookings per minute | Wait and retry |

Postman: `client.my-packages.sessions.store` › "404 Foreign package not found on session create", "409 Session key reused with different input", "422 Package not active on session create", "422 No session remains to book", "422 Session create starts after package expiry".

#### `POST /orders/{order}/pay` (purchase and session)

See [orders](orders.md) for the full pay error table. Package-specific recorded examples:

Postman: `client.orders.pay` › "200 Package purchase payment failed" (simulate_failure), "200 Package purchase payment succeeded".

#### `POST /orders/{order}/cancel` (purchase and session)

See [cancellation](cancellation.md) for the full cancel error table. Package-specific recorded examples:

| HTTP | `error_code` | When | App action |
|------|--------------|------|------------|
| 422 | `PACKAGE_PURCHASE_CANCELLATION_UNAVAILABLE` | Paid purchase cancel is not allowed | Show cannot-cancel state |

Postman: `client.orders.cancel` › "200 Unpaid package purchase cancelled", "200 Package session cancelled and hold released", "422 Paid package purchase cancellation unavailable".

## 4. Statuses and flags

Purchased package statuses are `pending_payment`, `active`, `consumed`, `expired`, `cancelled`, and `refunded`. List `active` filters to active; `finished` includes consumed, expired, cancelled and refunded. A held session counts as used until released; `sessions_remaining` is total minus used. Package and item `can_book_session` are live checks; item `booking_unavailable_reason` can be `package_not_active`, `no_sessions_left`, `service_unavailable` or `provider_unavailable`. Re-fetch after each order transition. A session start equal to expiry is allowed; a later start is refused. An open session postpones final package settlement.

## Data model

Purchases snapshot validity, item name, duration, allocated value and package commission. The client receives UUIDs and money strings. A purchase has no visit address; sessions have an owned service address. The final completed session carries the allocation remainder for settlement.

## 5. Dart models

Use the shared order and enum models from [orders](orders.md), with nullable fields in the purchase address object and the package fields described above. Match models against recorded examples once available.

## 6. Business rules

Only approved, visible and eligible packages can be purchased. Payment activates the package for its snapshotted validity period. The prepaid service line is zero on session orders; any delivery charge follows normal payment and cancellation rules. Rejection, expiry or cancellation releases the hold once. Purchase refunds remain unimplemented; full wallet payment is supported (TD-164).

## 7. Notifications and real-time events

Successful purchase writes `package_purchased` to the customer inbox and emits `order.updated` with reason `package_purchased`. Session requests use the existing provider order-request notifications and subsequent order events. See [orders](orders.md) and [API conventions](../API_CONVENTIONS.md).

## 8. Localization and UI notes

Use API status labels, format SAR amounts as decimal strings, and display times in the customer's locale; slot dates are Saudi-local.

## 9. Integration checklist

- [ ] Parse UUIDs, nullable address, money strings and status labels.
- [ ] Drive purchase and booking actions from `can_buy` and `can_book_session`.
- [ ] Handle loading, empty, expired and failure states; refresh on order events.
- [ ] Test Arabic RTL and English.

## 10. Acceptance scenarios

| AC ID | Scenario | Expected |
|-------|----------|----------|
| AC-CUST-008 | Purchase an eligible package | Paid purchase activates the snapshotted package. |
| AC-CUST-013 | Book a purchased session | Available scheduled visit holds one session; provider accepts before payment. |
| AC-CUST-015 | Payment fails | Package stays pending and payment may be retried before deadline. |
| AC-CUST-020 | Cancel | Unpaid purchase cancels; paid purchase refund is deferred; session hold is released. |

## 11. Open decisions and known limitations

FR-03 interpretation, equal allocation, expiry boundary, interim order VAT `0.00` (DEC-09), purchase refunds and zero-charge paid are **awaiting client confirmation**. A real gateway remains unimplemented; see TD-94 and TD-128. Wallet payment is supported under TD-164.

### Wallet payment (TD-164)

`POST /api/v1/client/orders/{order}/pay` accepts `method: wallet` for a full order or package purchase when enabled and adequately funded. Otherwise it returns 422 `WALLET_PAYMENTS_DISABLED` or `WALLET_INSUFFICIENT_BALANCE`. `wallet_plus_gateway` is rejected. See [wallet](wallet.md). Postman: `client.orders.pay` › "200 Wallet payment".
