> **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 — Outlet API handoff (flutter)

> **Verification boundary:** The detailed contract below was derived from repository source, not from live HTTP captures. Fields explicitly marked unverified remain open. The obsolete route-only inventory has been removed to avoid contradictory placeholders.

## Controller-reviewed contracts


All URLs relative to `/api/v1/`. Example values are **illustrative**, not captured from a live server. Angle-bracket text means a placeholder, not a literal API value. Error statuses are listed only when supported by controller code.

**Coverage in this document:** 3 endpoints; this is NOT an assertion that the entire module is complete.

## `GET /api/v1/fees`

**Purpose:** Read current fee, tax, policy and links.
**Access:** Public

| Request field | Type | Required | Validation |
|---|---|---|---|
| — | — | — | No request fields |

**Example request:**

```http
GET /api/v1/fees
Content-Type: application/json

{}
```

**Example success response — HTTP 200:**

```json
{
  "data": {
    "currency": "SAR",
    "commission": {
      "rate": "15.00",
      "rate_label": "<localized>",
      "label": "<localized>",
      "hint": "<localized>"
    },
    "service_fee": {
      "enabled": false,
      "type": "<configured>",
      "amount": null,
      "rate": null,
      "label": "<localized>",
      "value_label": "<localized>"
    },
    "tax": {
      "enabled": false,
      "vat_rate": "0.00",
      "prices_include_vat": false,
      "note": null
    },
    "policy": {
      "title": "<localized>",
      "updated_at": null,
      "updated_label": null,
      "items": [
        "<localized>"
      ]
    },
    "endpoints": {
      "seller_net": "/api/v1/fees/seller-net",
      "quote": "/api/v1/fees/quote"
    }
  }
}
```

**Response field types:**

| Field | Type |
|---|---|
| `data.currency` | string |
| `data.commission.rate` | string |
| `data.commission.rate_label` | string |
| `data.commission.label` | string |
| `data.commission.hint` | string |
| `data.service_fee.enabled` | boolean |
| `data.service_fee.type` | string |
| `data.service_fee.amount` | null |
| `data.service_fee.rate` | null |
| `data.service_fee.label` | string |
| `data.service_fee.value_label` | string |
| `data.tax.enabled` | boolean |
| `data.tax.vat_rate` | string |
| `data.tax.prices_include_vat` | boolean |
| `data.tax.note` | null |
| `data.policy.title` | string |
| `data.policy.updated_at` | null |
| `data.policy.updated_label` | null |
| `data.policy.items` | array |
| `data.policy.items[]` | string |
| `data.endpoints.seller_net` | string |
| `data.endpoints.quote` | string |

**Notes / errors:** Illustrative rate and currency; actual values from policy.

**Source:** [Pricing/Interfaces/Http/Presenters/PricingPresenter.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Pricing/Interfaces/Http/Presenters/PricingPresenter.php)

---

## `GET /api/v1/fees/seller-net`

**Purpose:** Preview seller net after commission.
**Access:** Public

| Request field | Type | Required | Validation |
|---|---|---|---|
| `price` | decimal string query | yes | PricingRequest::AMOUNT |
| `old_price` | decimal string query | no | nullable; PricingRequest::AMOUNT |
| `sold` | boolean query | no | nullable boolean |

**Example request:**

```http
GET /api/v1/fees/seller-net?price=190.00&old_price=220.00&sold=false
```

**Example success response — HTTP 200:**

```json
{
  "data": {
    "currency": "SAR",
    "price": "190.00",
    "commission": "28.50",
    "commission_rate": "15.00",
    "seller_net": "161.50",
    "text": "<localized preview>"
  }
}
```

**Response field types:**

| Field | Type |
|---|---|
| `data.currency` | string |
| `data.price` | string |
| `data.commission` | string |
| `data.commission_rate` | string |
| `data.seller_net` | string |
| `data.text` | string |

**Notes / errors:** Values illustrative and policy-dependent.

**Source:** [Pricing/Interfaces/Http/Presenters/PricingPresenter.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Pricing/Interfaces/Http/Presenters/PricingPresenter.php)

---

## `GET /api/v1/fees/quote`

**Purpose:** Preview buyer total and seller payout.
**Access:** Public

| Request field | Type | Required | Validation |
|---|---|---|---|
| `items_total` | decimal string query | yes | PricingRequest::AMOUNT |
| `delivery_fee` | decimal string query | no | nullable; PricingRequest::AMOUNT |
| `pieces` | integer query | no | nullable; min:0 max:1000 |

**Example request:**

```http
GET /api/v1/fees/quote?items_total=200.00&delivery_fee=15.00&pieces=2
```

**Example success response — HTTP 200:**

```json
{
  "data": {
    "currency": "SAR",
    "items_total": "200.00",
    "service_fee": "0.00",
    "service_fee_type": "<configured>",
    "service_fee_rate": null,
    "delivery_fee": "15.00",
    "buyer_total": "215.00",
    "commission": "30.00",
    "commission_rate": "15.00",
    "seller_net": "170.00",
    "tax_display": {
      "enabled": false,
      "rate": "0.00",
      "prices_include_vat": false,
      "base": "0.00",
      "amount": "0.00",
      "included_amount": "0.00",
      "note": null
    },
    "lines": [
      {
        "key": "items",
        "label": "<localized>",
        "amount": "200.00",
        "display": null,
        "informational": false
      },
      {
        "key": "delivery",
        "label": "<localized>",
        "amount": "15.00",
        "display": null,
        "informational": false,
        "pending": false
      }
    ],
    "total": {
      "label": "<localized>",
      "amount": "215.00",
      "note": null
    },
    "seller": {
      "lines": [
        {
          "key": "item_price",
          "label": "<localized>",
          "amount": "200.00"
        },
        {
          "key": "commission",
          "label": "<localized>",
          "amount": "-30.00"
        },
        {
          "key": "seller_net",
          "label": "<localized>",
          "amount": "170.00"
        }
      ],
      "note": "<localized>"
    }
  }
}
```

**Response field types:**

| Field | Type |
|---|---|
| `data.currency` | string |
| `data.items_total` | string |
| `data.service_fee` | string |
| `data.service_fee_type` | string |
| `data.service_fee_rate` | null |
| `data.delivery_fee` | string |
| `data.buyer_total` | string |
| `data.commission` | string |
| `data.commission_rate` | string |
| `data.seller_net` | string |
| `data.tax_display.enabled` | boolean |
| `data.tax_display.rate` | string |
| `data.tax_display.prices_include_vat` | boolean |
| `data.tax_display.base` | string |
| `data.tax_display.amount` | string |
| `data.tax_display.included_amount` | string |
| `data.tax_display.note` | null |
| `data.lines` | array |
| `data.lines[].key` | string |
| `data.lines[].label` | string |
| `data.lines[].amount` | string |
| `data.lines[].display` | null |
| `data.lines[].informational` | boolean |
| `data.total.label` | string |
| `data.total.amount` | string |
| `data.total.note` | null |
| `data.seller.lines` | array |
| `data.seller.lines[].key` | string |
| `data.seller.lines[].label` | string |
| `data.seller.lines[].amount` | string |
| `data.seller.note` | string |

**Notes / errors:** Conditional service_fee and vat lines. Amounts illustrative. If delivery fee omitted, delivery line amount null and pending=true.

**Source:** [Pricing/Interfaces/Http/Presenters/PricingPresenter.php](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Pricing/Interfaces/Http/Presenters/PricingPresenter.php)

---


---
