---
feature: Provider service management and pricing
slug: services-pricing
surface: provider
consumer: flutter
version: 1.1.0
status: ready
brd_version: "1.3"
brd_ids: [PROV-009, PROV-010]
business_rules: [BR-03, BR-05, BR-06, BR-08]
decisions: [SCR-35, TD-86, TD-90, TD-01, TD-09, TD-11, TD-12, TD-14, TD-19, TD-33, TD-34, TD-42, TD-56, TD-57, TD-60, TD-64, TD-70, TD-71, TD-74]
schema_tables: [providers, provider_categories, provider_services, categories, category_translations, services, service_translations]
screens: ["provider--services-pricing--*"]
related_docs: [onboarding.md, profile.md, ../admin/services.md, ../admin/providers.md, ../admin/registration-review.md]
last_updated: 2026-10-25
---

# Service management and pricing — Flutter Integration Guide (provider)

> **Base URL:** `{HOST}/api/v1/provider`

## Version history

| Version | Date | Type | Summary | App action required |
|---------|------|------|---------|---------------------|
| 1.1.0 | 2026-10-25 | MINOR | `GET /my-categories/available` lists the categories she can still request, and §2.1 specifies the "add a category" screen the prototype lacks (BRD PROV-009, SCR-35). | Build the add-category entry and sheet from §2.1. |
| 1.0.1 | 2026-10-25 | PATCH | The admin can now approve or reject an extra-category request ([registration-review.md](../admin/registration-review.md), AC-PROV-009); the provider receives an in-app notice (`provider_category_reviewed`). No contract change. | Show the new notice type; `status` moves `requested` → `approved`/`rejected` as documented. |
| 1.0.0 | 2026-10-22 | Initial | Approved categories, extra-category requests, active catalog tree and atomic base/choice prices. | Integrate the seven endpoints; preserve the onboarding category catalog. |

## Changelog

### 1.1.0 — 2026-10-25

- **Added:** `GET /my-categories/available` (approved provider): active categories she has no assignment for. Screen specification §2.1 for the missing add-category entry (SCR-35, TD-90).
- **Changed / Fixed / Removed / Deprecated:** —
- **Breaking:** No.
- **Endpoints affected:** `GET /my-categories/available` (new).
- **App action required:** add an "Add a category" entry to `provider--services-pricing--01-list` and the sheet of §2.1; keep showing requested and rejected categories from `GET /my-categories`.
- **BRD / decisions:** PROV-009, AC-PROV-009, WF-02, TD-86, TD-90.

### 1.0.1 — 2026-10-25

- **Added:** an admin review path for extra-category requests; one notice per decision in the shared inbox (event `provider_category_reviewed`, payload `category_request_id`, `category_id`, `status`, `reason`).
- **Changed / Fixed / Removed / Deprecated:** N/A.
- **Breaking:** No.
- **Endpoints affected:** none here; the decision happens in the admin API.
- **App action required:** none mandatory; refresh `GET /my-categories` when the notice arrives. A rejected request stays `rejected` (final, TD-70).
- **BRD / decisions:** AC-PROV-009, TD-70, TD-86.

### 1.0.0 — 2026-10-22

- **Added:** seven provider category/pricing endpoints, own category assignments, exact ranges, nested option groups, visibility and summary.
- **Changed:** onboarding services completion now uses the same complete-pricing Domain rule as enable/toggle.
- **Fixed:** nested choice UUID resolution at the common request boundary.
- **Removed / Deprecated:** N/A.
- **Breaking:** No; existing `GET /categories` retained.
- **Endpoints affected:** §3 and the onboarding completion calculation.
- **App action required:** submit one atomic root form including explicit free choice zeroes; show pending category review separately.
- **BRD / decisions:** PROV-009/010, BR-03/05/06, TD-42/70/71/74.

## 1. Business summary

After account approval, the provider can request extra main categories, turn approved categories on/off, select bookable services and price every option. Admin owns definitions and allowed ranges; the provider owns actual prices. Visibility requires a complete active base and prices for every active choice of every active group, including optional groups and free choices. These prices feed later booking calculations; saving a price does not certify full coverage or availability.

## 2. User flow and screens

| Step | Screen | Endpoint | UI behavior |
|------|--------|----------|-------------|
| 1 | `provider--services-pricing--01-list` | `GET /my-categories`, `GET /services?category_id=` | Use approved/enabled chips; show name, description, reference/min/max and duration. Requested/rejected assignments stay visible with status, not selectable for pricing. |
| 2 | `provider--services-pricing--03-price-editor` | `PUT /services/{service}` | Edit base price; save inactive drafts or submit complete pricing with `is_active=true`. |
| 3 | `provider--services-pricing--04-addon-prices-p1/p2` | Same atomic PUT | Each type-2 group has independent selection rules; send type-3 prices, including explicit zero for free choices. |
| 4 | `provider--services-pricing--02-save` | `GET /services/summary` | Show priced/enabled root counts; save each modified root form, report any failed root, then refetch summary. There is no multi-root bulk transaction. |
| 5 | Category/visibility controls | `POST /categories`, both PATCH toggles | Use explicit desired booleans; refetch state after an uncertain network result. New categories await admin review ([registration-review.md](../admin/registration-review.md)). |

Keep the existing `GET /categories` catalog for onboarding and the extra-category picker. It requires a provider token but does not require approval. Operational endpoints below require approval.

### 2.1 Screen addition: request a new category (SCR-35, not in the prototype)

The BRD requires it (PROV-009: *providers cannot add a new main service without admin approval; they submit a service-addition request and admin review enables it*), but `provider--services-pricing--01-list` shows only the approved category chips. Until design draws it, build this:

```
┌ خدماتي وأسعاري ──────────────────────┐
│ التصنيف الرئيسي                       │
│ (المكياج) (الشعر) (الأظافر) (+ إضافة تصنيف)  ← trailing chip, only when `available` is not empty
│ ⏳ العناية بالجسم · قيد المراجعة         ← requested: greyed chip, not selectable
│ ✕ الحواجب · مرفوض                      ← rejected: greyed chip, final
└──────────────────────────────────────┘
        tap "+ إضافة تصنيف"
┌ إضافة تصنيف جديد ─────────────────────┐
│ ○ العناية بالجسم   عناية كاملة …        │  ← GET /my-categories/available (name, description, image)
│ ○ الحواجب                              │
│ سيراجع فريق جوشن الطلب. بعد الموافقة     │
│ يمكنك اختيار خدماته وتسعيرها.            │
│ [ إرسال الطلب ]                         │  ← POST /categories { category_id }
└──────────────────────────────────────┘
```

| State | Source | UI |
|-------|--------|----|
| Can request | `GET /my-categories/available` (non-empty) | Show the "+ Add a category" chip; hide it when the list is empty |
| Requested | `GET /my-categories` item with `status.value = requested` | Grey chip "Under review", not selectable (`can_toggle = false`) |
| Approved | `status.value = approved` | Normal chip; pricing opens (§3.4) |
| Rejected | `status.value = rejected` | Grey chip "Rejected"; the request cannot be repeated (409) — contact support |
| Decision | Inbox notice `provider_category_reviewed` (`data.status`: `approved` or `rejected`, `data.reason`) | Open the list and refresh both endpoints |

After a successful `POST /categories` (201) move the category from the sheet to the chip row as *requested*. Errors: `409 ENTITY_ALREADY_EXISTS` (already requested — refresh both lists), `422 BUSINESS_RULE_VIOLATED` (category inactive), `403` (account not approved). Joshen decides in the dashboard ([registration-review.md](../admin/registration-review.md) §3.2).

## 3. Endpoints

All IDs are UUID strings; prices are exact two-decimal SAR strings. Send `Accept: application/json`, `Authorization: Bearer …`, and `Accept-Language: ar|en`. See [API_CONVENTIONS.md](../API_CONVENTIONS.md). No `X-City` or `Idempotency-Key` is required.

### 3.1 Own categories

`GET /api/v1/provider/my-categories`

Auth: Bearer JWT, `app=provider`, active user; approved provider account required. No extra headers or endpoint-specific throttle. Responses are private/no-store.

No body or query fields. Each `data[]` item has assignment `id`, catalog `category_id`, `name`, `image`, catalog `is_active`, enum `status`, `is_enabled` and `can_toggle`. Use assignment `id` in the category PATCH; use `category_id` in the service filter.

Success — **200**. Real MySQL HTTP response: [captured example](../postman-collection.json) (Postman: `provider.my-categories.index` › "200 Approved and requested own categories").

```json
{
  "status": "success",
  "message": "",
  "data": [
    {
      "id": "01a16307-08a1-7161-ad07-9d5c794fbf40",
      "category_id": "01a16307-089e-724c-af8e-e7be7043b3de",
      "name": "Sample-bqju11294387",
      "image": "https://ui-avatars.com/api/?name=C&background=fef3c7&color=d97706&size=200",
      "is_active": true,
      "status": {
        "value": "approved",
        "label": "Approved"
      },
      "is_enabled": true,
      "can_toggle": true
    },
    {
      "id": "01a16307-08c2-7380-b140-4f9ed4ed8f8e",
      "category_id": "01a16307-08b4-7346-a0b1-cea0c98d1af9",
      "name": "Sample-lkdl12982307",
      "image": "https://ui-avatars.com/api/?name=C&background=fef3c7&color=d97706&size=200",
      "is_active": true,
      "status": {
        "value": "requested",
        "label": "Requested"
      },
      "is_enabled": true,
      "can_toggle": false
    }
  ]
}
```

### 3.1b Categories she can still request

`GET /api/v1/provider/my-categories/available`

Auth: Bearer JWT, `app=provider`, approved account. No query or body. Returns the active catalog categories **without any assignment** for her (so requested, approved and rejected ones are not repeated), in catalog order; an empty list means there is nothing left to request. Private/no-store. Postman: `provider.my-categories.available` › "200 Categories she can still request".

```json
{
  "status": "success",
  "message": "",
  "data": [
    {
      "id": "01a17221-da9f-7293-9072-5f191c1150d7",
      "name": "Nails",
      "description": "Nail care",
      "image": "https://ui-avatars.com/api/?name=C&background=fef3c7&color=d97706&size=200"
    }
  ]
}
```

`id` is the catalog category uuid — send it as `category_id` to `POST /categories`.

### 3.2 Request an extra category

`POST /api/v1/provider/categories`

Auth: Bearer JWT, `app=provider`, active user; approved provider account required. No extra headers or endpoint-specific throttle. Responses are private/no-store.

Body: `category_id` required UUID of an existing active catalog category. The unique assignment starts `requested`, `is_enabled=true`, with no review attribution. Existing assignments return 409; this route never resets review state.

Success — **201**. Real MySQL HTTP response: [captured example](../postman-collection.json) (Postman: `provider.my-categories.store` › "201 Extra category requested for admin review").

```json
{
  "status": "success",
  "message": "",
  "data": {
    "id": "01a16307-08c2-7380-b140-4f9ed4ed8f8e",
    "category_id": "01a16307-08b4-7346-a0b1-cea0c98d1af9",
    "name": "Sample-lkdl12982307",
    "image": "https://ui-avatars.com/api/?name=C&background=fef3c7&color=d97706&size=200",
    "is_active": true,
    "status": {
      "value": "requested",
      "label": "Requested"
    },
    "is_enabled": true,
    "can_toggle": false
  }
}
```

### 3.3 Toggle an owned category

`PATCH /api/v1/provider/categories/{provider_category_id}/toggle`

Auth: Bearer JWT, `app=provider`, active user; approved provider account required. No extra headers or endpoint-specific throttle. Responses are private/no-store.

Path: owned `provider_categories.uuid`, never catalog UUID. Body: required boolean `is_enabled`. Assignment must be approved. Turning a category off preserves all service/choice prices and hides its offers through the existing SQL view.

Success — **200**. Real MySQL HTTP response: [captured example](../postman-collection.json) (Postman: `provider.my-categories.toggle` › "200 Disable owned approved category").

```json
{
  "status": "success",
  "message": "",
  "data": {
    "id": "01a16307-08a1-7161-ad07-9d5c794fbf40",
    "category_id": "01a16307-089e-724c-af8e-e7be7043b3de",
    "name": "Sample-bqju11294387",
    "image": "https://ui-avatars.com/api/?name=C&background=fef3c7&color=d97706&size=200",
    "is_active": true,
    "status": {
      "value": "approved",
      "label": "Approved"
    },
    "is_enabled": false,
    "can_toggle": true
  }
}
```

### 3.4 List active services and options

`GET /api/v1/provider/services?category_id={category_id}`

Auth: Bearer JWT, `app=provider`, active user; approved provider account required. No extra headers or endpoint-specific throttle. Responses are private/no-store.

Query: required `category_id` catalog UUID belonging to an approved, enabled, active category of this provider. Unpaginated `data[]` of type-1 roots, `option_groups[]` type 2 and `choices[]` type 3. Only active nodes under active ancestors appear. Base/choice `price`, `is_active`, `duration_min` are null until saved; groups have no own prices. `default_duration_min` is the admin duration; nullable `duration_min` is the provider override. `reference_price` is nullable. `can_price`/`can_toggle` describe available controls, with Domain validation on each attempt.

Success — **200**. Real MySQL HTTP response: [captured example](../postman-collection.json) (Postman: `provider.services.index` › "200 Active service tree with own prices and free choice").

```json
{
  "status": "success",
  "message": "",
  "data": [
    {
      "id": "01a16307-054c-700a-80bf-b7b06808b45a",
      "name": "Makeup",
      "description": null,
      "default_duration_min": 60,
      "min_price": "50.00",
      "max_price": "500.00",
      "reference_price": null,
      "price": "500.00",
      "is_active": true,
      "duration_min": null,
      "can_price": true,
      "can_toggle": true,
      "option_groups": [
        {
          "id": "01a16307-0551-7097-8fc0-021d4665cc85",
          "name": "Sample-ekhn67535231",
          "description": null,
          "children_required": true,
          "children_selection": {
            "value": "single",
            "label": "Single"
          },
          "choices": [
            {
              "id": "01a16307-0558-711a-969e-56e404a8b280",
              "name": "Sample-pcvs46387755",
              "description": null,
              "default_duration_min": 10,
              "min_price": "10.00",
              "max_price": "200.00",
              "reference_price": null,
              "price": "200.00",
              "is_active": true,
              "duration_min": null,
              "is_free": false
            },
            {
              "id": "01a16307-055c-71e8-87b7-fe345d45897d",
              "name": "Sample-vwsz36097240",
              "description": null,
              "default_duration_min": 10,
              "min_price": "0.00",
              "max_price": "0.00",
              "reference_price": null,
              "price": "0.00",
              "is_active": true,
              "duration_min": null,
              "is_free": true
            }
          ]
        }
      ]
    }
  ]
}
```

### 3.5 Save base and choice prices

`PUT /api/v1/provider/services/{service}`

Auth: Bearer JWT, `app=provider`, active user; approved provider account required. No extra headers or endpoint-specific throttle. Responses are private/no-store.

Path: active type-1 `services.uuid` under an eligible owned category.

| Field | Required | Validation / behavior |
|-------|----------|-----------------------|
| price | yes | Numeric, 0–2 decimal places; Domain checks inclusive admin min/max, returning PRICE_OUT_OF_RANGE for outliers. |
| duration_min | no | Null or integer 1…2147483647; omission preserves, null restores admin duration. |
| is_active | yes | Boolean; true requires complete base and every active choice price. |
| choices | present | List, may be empty for an inactive draft or previously saved complete choices. |
| choices.* | yes per item | Only service_id and price. |
| choices.*.service_id | yes | Distinct existing service UUID; Domain requires active type-3 choice of this root in an active group. |
| choices.*.price | yes | Numeric, 0–2 decimals, within that choice range. A 0–0 choice requires explicit 0. |

Each supplied choice upserts an active provider price. Omitted choice rows are preserved; they are never deleted or zero-filled. Root and supplied prices commit together, or every write rolls back. Groups cannot be priced through either route or body. An inactive draft may remain incomplete; an enabled form cannot.

Success — **200**. Real MySQL HTTP response: [captured example](../postman-collection.json) (Postman: `provider.services.update` › "200 Complete base and paid and free choices at range edge 500.00").

```json
{
  "status": "success",
  "message": "",
  "data": {
    "id": "01a16307-054c-700a-80bf-b7b06808b45a",
    "name": "Makeup",
    "description": null,
    "default_duration_min": 60,
    "min_price": "50.00",
    "max_price": "500.00",
    "reference_price": null,
    "price": "500.00",
    "is_active": true,
    "duration_min": null,
    "can_price": true,
    "can_toggle": true,
    "option_groups": [
      {
        "id": "01a16307-0551-7097-8fc0-021d4665cc85",
        "name": "Sample-ekhn67535231",
        "description": null,
        "children_required": true,
        "children_selection": {
          "value": "single",
          "label": "Single"
        },
        "choices": [
          {
            "id": "01a16307-0558-711a-969e-56e404a8b280",
            "name": "Sample-pcvs46387755",
            "description": null,
            "default_duration_min": 10,
            "min_price": "10.00",
            "max_price": "200.00",
            "reference_price": null,
            "price": "200.00",
            "is_active": true,
            "duration_min": null,
            "is_free": false
          },
          {
            "id": "01a16307-055c-71e8-87b7-fe345d45897d",
            "name": "Sample-vwsz36097240",
            "description": null,
            "default_duration_min": 10,
            "min_price": "0.00",
            "max_price": "0.00",
            "reference_price": null,
            "price": "0.00",
            "is_active": true,
            "duration_min": null,
            "is_free": true
          }
        ]
      }
    ]
  }
}
```

### 3.6 Toggle service visibility

`PATCH /api/v1/provider/services/{service}/toggle`

Auth: Bearer JWT, `app=provider`, active user; approved provider account required. No extra headers or endpoint-specific throttle. Responses are private/no-store.

Path: active type-1 service UUID in eligible category. Body: required boolean `is_active`. Enabling reuses the exact save completeness check; missing base/choice prices return 422 and keep previous visibility. Disable before first pricing is a no-op with nullable saved fields. No price row is fabricated.

Success — **200**. Real MySQL HTTP response: [captured example](../postman-collection.json) (Postman: `provider.services.toggle` › "200 Explicitly disable a service").

```json
{
  "status": "success",
  "message": "",
  "data": {
    "id": "01a16307-075a-71aa-9442-67e35ffdf8d0",
    "name": "Makeup",
    "description": null,
    "default_duration_min": 60,
    "min_price": "50.00",
    "max_price": "500.00",
    "reference_price": null,
    "price": "100.00",
    "is_active": false,
    "duration_min": null,
    "can_price": true,
    "can_toggle": true,
    "option_groups": []
  }
}
```

### 3.7 Summary

`GET /api/v1/provider/services/summary`

Auth: Bearer JWT, `app=provider`, active user; approved provider account required. No extra headers or endpoint-specific throttle. Responses are private/no-store.

No body or query fields. `priced_count` counts saved base rows, active or inactive, in eligible categories with active roots. `enabled_count` counts active complete roots using the shared Domain predicate. Groups/choices are excluded from both totals.

Success — **200**. Real MySQL HTTP response: [captured example](../postman-collection.json) (Postman: `provider.services.summary` › "200 One complete enabled service").

```json
{
  "status": "success",
  "message": "",
  "data": {
    "priced_count": 1,
    "enabled_count": 1
  }
}
```

### 3.8 Errors and app actions

| HTTP | error_code | Cause / action |
|------|------------|----------------|
| 401 | UNAUTHENTICATED | Refresh/sign in using shared auth behavior. |
| 403 | PERMISSION_DENIED / ACCOUNT_INACTIVE | Wrong app or inactive/unapproved account; show review/account state, prevent operational actions. |
| 404 | absent (`data:null`) | Unknown/integer service or missing/foreign assignment; refetch catalog/own list. |
| 422 | absent (`data.errors`) | Request shape, UUID reference, precision, missing boolean/choices, duplicate choices; mark fields from `data.errors`, falling back to the localized message (TD-02). |
| 422 | PRICE_OUT_OF_RANGE | `data.node.id/name`, `min_price`, `max_price` identify the offending base/choice; focus its price input. |
| 422 | BUSINESS_RULE_VIOLATED | Category unavailable, group/root/choice membership invalid, inactive nodes or incomplete enable. Refetch active tree if it changed. Incomplete enable adds `data.unpriced_choices[]` with UUID/name; when the base is missing it is included too. Highlight all returned nodes. |
| 409 | ENTITY_ALREADY_EXISTS | Category is already linked; refresh its existing status rather than resubmitting. |

```json
{
  "status": "fail",
  "message": "The price for Makeup must be between 50.00 and 500.00 SAR.",
  "data": {
    "error_code": "PRICE_OUT_OF_RANGE",
    "correlation_id": "4582c4f6-f198-41a2-912b-342bbf4900e1",
    "node": {
      "id": "01a16307-062a-70b2-be24-d916f43c2ae2",
      "name": "Makeup"
    },
    "min_price": "50.00",
    "max_price": "500.00"
  }
}
```
```json
{
  "status": "fail",
  "message": "Price every active choice before enabling the service. Missing prices: Sample-isev28101216, Sample-ltwg18466272.",
  "data": {
    "error_code": "BUSINESS_RULE_VIOLATED",
    "correlation_id": "fcdbd4be-ad7d-4cf9-a607-1fd07f78e602",
    "unpriced_choices": [
      {
        "id": "01a16307-0760-7308-acb6-8b0417d5a09f",
        "name": "Sample-isev28101216"
      },
      {
        "id": "01a16307-0763-7376-ba41-c14227740219",
        "name": "Sample-ltwg18466272"
      }
    ]
  }
}
```

## 4. Statuses and enums

| Enum / flag | Value | Meaning / action |
|-------------|-------|------------------|
| assignment.status | requested | Pending admin review; can_toggle=false. |
| assignment.status | approved | can_toggle=true; services require is_enabled plus active category. |
| assignment.status | rejected | Not eligible, no implicit re-request route. |
| children_selection | single / multiple | Localized enum on each group; booking must enforce each nonempty active group independently. |
| children_required | true / false | Selection rule for that group; does not exempt its choices from pricing completeness. |
| base/choice.is_active | null / false / true | No price saved / saved inactive / saved active. |

## Data model

| Table / view | Read / write | Notes |
|--------------|--------------|-------|
| providers | read + lock | Approval gate, provider_id FKs target providers.user_id. |
| provider_categories | read + write | Unique owner/category assignment; requested additions and own enabled flag only. |
| provider_services | read + write | Existing provider-owned actual prices on types 1/3, duration override and active flag. |
| categories/category_translations | read + lock | Active flat main categories. |
| services/service_translations | read + lock | Active root → groups → choices; admin range/reference/duration. |
| v_bookable_provider_services | read in acceptance tests | Same-provider complete prices plus account/category gates. |
| v_selectable_provider_addons | read in acceptance tests | Active type-3 prices under active groups and eligible parent root. |

No migration or new pricing table. Existing `trg_ps_price_ins/upd` remain safety nets. Mutations lock provider, category and nodes before validating and persisting, serializing against admin catalog/range changes.

## 5. Dart models

```dart
typedef Json = Map<String, dynamic>;
class ProviderPrice {
  final String id;
  final String? name, description, price, referencePrice;
  final String minPrice, maxPrice;
  final int defaultDurationMin;
  final int? durationMin;
  final bool? isActive;
  ProviderPrice.fromJson(Json j)
      : id = j['id'] as String, name = j['name'] as String?,
        description = j['description'] as String?, price = j['price'] as String?,
        referencePrice = j['reference_price'] as String?,
        minPrice = j['min_price'] as String, maxPrice = j['max_price'] as String,
        defaultDurationMin = j['default_duration_min'] as int,
        durationMin = j['duration_min'] as int?, isActive = j['is_active'] as bool?;
}
```

Parse root `option_groups` into groups with `id/name/description`, boolean `children_required`, `{value,label}` selection and typed `choices`. Choice extends the price fields with boolean `is_free`. Category items must retain both assignment and catalog IDs; use money strings in outgoing forms.

## 6. Business rules enforced by the backend

| Rule | Enforcement | User effect |
|------|-------------|-------------|
| BR-03 / PROV-004 | Approved provider operational middleware plus transactional eligibility check. | Pending providers cannot price. |
| BR-05 / TD-42 | Root type1, group type2, choice type3 membership and active ancestors. | Groups are structural controls, never priced. |
| BR-06 / TD-71 | Exact inclusive ranges; complete same-provider active pricing before enable. | Highlight node/range or missing-node list; no partial commit. |
| PROV-009 / TD-70 | Extra category requested only, no auto-approval. | Pending chip and later admin review. |
| TD-64/71 | Same completeness predicate in onboarding and summary/toggle. | A base price alone cannot clear the services checklist item. |

## 7. Notifications and real-time events

When the admin decides an extra-category request, one in-app notice is written to the shared inbox (`GET /api/v1/notifications` with the provider token): event `provider_category_reviewed`, `data` = `{category_request_id, category_id, status: approved|rejected, reason}`; title/body in the provider's language. Requesting and pricing themselves send nothing.

## 8. Localization and UI notes

API text falls back to Arabic when English catalog text is absent. Enum labels and validation/range errors follow Accept-Language. Show "free" for is_free, but still submit zero. Client ranges improve input feedback; server rechecks live ranges. Empty active catalog, loading, validation failure and a changed category state need distinct screen states.

## 9. Integration checklist

- [ ] Use my-categories for assignments and categories for catalog choices.
- [ ] Preserve both public UUID types and use backend status/can_toggle flags.
- [ ] Render only active tree nodes returned by the API.
- [ ] Send every free choice zero explicitly and price optional-group choices too.
- [ ] Save each edited root atomically; refresh list/summary after all results.
- [ ] Handle all errors in §3.8 without assuming a failed form partially saved.
- [ ] Keep incomplete drafts inactive; show missing nodes before enabling.
- [ ] Verify Arabic/English and empty/loading/error states.

## 10. Acceptance scenarios

| AC ID | Scenario | Expected |
|-------|----------|----------|
| AC-PROV-009 | Own categories, extra request, category toggle and foreign/unapproved category. | Requested status visible in onboarding; no unauthorized pricing/toggle. |
| AC-PROV-010 | Inclusive edges, negative/out-of-range price, group pricing and free zero. | Valid exact money persists; invalid form rejected with typed errors. |
| AC-PROV-010 | Missing prices, optional/multiple groups, inactive saved choice row. | Enable/toggle denied; onboarding and SQL eligibility agree. |
| AC-PROV-009/010 | Pending account, other-app token, integer references and missing routes. | Correct denial with no writes. |

## 11. Open decisions and known limitations

Booking/customer visibility also requires address/coverage/availability under BR-08. Empty/inactive groups have no active choices to select (TD-42). Saving prices does not complete booking acceptance. Runtime local verification is separate from production rollout and Flutter screen acceptance.

## 12. Verification evidence

Local MySQL `joshen_testing`: full suite **778 tests / 6,837 assertions passed**; affected provider pricing/profile and provider/driver onboarding capture run **120 tests / 1,161 assertions passed**. `postman:generate --check` is green for 172 exported routes; all 13 newly introduced endpoints are complete, none added to the 454 pre-existing baseline gaps. Pint and changed-document links/diff checks passed. Production rollout and Flutter acceptance were not tested.

`tests/Feature/Api/V1/Provider/ServicesPricingTest.php` contains AC-named MySQL HTTP tests and real TD-56 records in `docs/postman-collection.json` (saved responses of `provider.*`). Tests also compare completeness with both SQL views. Postman fields come from Form Requests; UUID/hash chaining is generated under TD-74. See the final execution report for aggregate counts.

## 13. Pending scope

Extra-category review is built (admin, AC-PROV-009). Checkout selection validation, availability/coverage, customer service discovery and package/order pricing snapshots remain their owning features. No admin actual-price writing or silent repricing was introduced.
