> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# Pricing — verified response schemas

Sources: `modules/Pricing/Routes/api.php`, `Interfaces/Http/Controllers/FeesController.php`, `Requests/{SellerNetRequest,QuoteRequest}.php`, `Presenters/PricingPresenter.php`, Core `ApiResponse.php`.

All three endpoints are public. `GET` query params; no JSON body. Monetary request fields are decimal strings and subject to the shared `PricingRequest::AMOUNT` validation rule (exact regex not rechecked here). Values in examples are **illustrative**, not calculations from a running server.

## GET /fees

No request fields. **200 `data` schema**:

| Field | Type |
|---|---|
| `currency` | string |
| `commission` | object: `rate`, `rate_label`, `label`, `hint` (strings) |
| `service_fee` | object: `enabled` boolean, `type` string, `amount` decimal string/null, `rate` percent string/null, `label` string, `value_label` string |
| `tax` | object: `enabled` boolean, `vat_rate` percent string, `prices_include_vat` boolean, `note` string/null |
| `policy` | object: `title` string, `updated_at` ISO datetime/null, `updated_label` string/null, `items` string[] |
| `endpoints` | object: `seller_net`, `quote` strings |

## GET /fees/seller-net

| Query | Type | Required | Rules |
|---|---|---|---|
| `price` | decimal string | Yes | Pricing amount rule |
| `old_price` | decimal string/null | No | Pricing amount rule |
| `sold` | boolean/null | No | boolean |

Example: `/fees/seller-net?price=190.00&old_price=220.00&sold=0`

**200 response shape (numbers are illustrative):**
```json
{"data":{"currency":"SAR","price":"190.00","commission":"28.50","commission_rate":"15.00","seller_net":"161.50","text":"<localized preview text>"}}
```
The currency and rate are policy-dependent; do not assume `SAR`/15% in production.

## GET /fees/quote

| Query | Type | Required | Rules |
|---|---|---|---|
| `items_total` | decimal string | Yes | Pricing amount rule |
| `delivery_fee` | decimal string/null | No | Pricing amount rule |
| `pieces` | integer/null | No | min 0, max 1000 |

Example: `/fees/quote?items_total=200.00&delivery_fee=15.00&pieces=2`

**200 response `data` fields** (all derived from `PricingPresenter::quote`):

| Field | Type / contents |
|---|---|
| `currency` | string |
| `items_total`, `service_fee`, `delivery_fee`, `buyer_total`, `commission`, `seller_net` | decimal strings |
| `service_fee_type` | string |
| `service_fee_rate` | percent string/null |
| `commission_rate` | percent string |
| `tax_display` | object: `enabled`, `rate`, `prices_include_vat`, `base`, `amount`, `included_amount`, `note` |
| `lines[]` | objects: `key`, `label`, `amount`, `display`, `informational`, sometimes `pending` |
| `total` | object: `label`, `amount`, `note` |
| `seller.lines[]` | objects: `key`, `label`, `amount` |
| `seller.note` | string |

When `delivery_fee` is omitted, the delivery `lines[]` entry has `amount: null`, `pending: true`, and a localized `display` explaining delivery is pending. VAT line appears only when enabled; service fee line only when positive. This means UI must not assume fixed `lines` length.
