# Quote

> Price a base product, a quantity and shipping (no address needed): cost per piece, lines, shipping fee, total and the minimum selling price.

Source: https://docs.b7r.app/quote

> Amounts, ids and limits in the examples are samples. Read the real values from the API.

## Price a product with shipping

`POST /v1/quote`

Prices a quantity of one base product with one technique and its zones, plus one shipment. It saves nothing and charges nothing.

Colour and size do not change the price: it depends on the product, the technique, the zones and the quantity. `technique_id` and `zone_ids` must be one of the product's `options`; zones no option prices answer `400 invalid_request` with `unknown_zone`.

There is no address in a quote: the shipping fee is the carrier's fee per shipment, which does not depend on the address.

Without `carrier_id`, your default carrier is used, or B7R's default carrier when you have not chosen one. An id that is not the product's, a technique it does not offer or an inactive carrier answers `400 invalid_request`; the error names the field and lists the accepted ids in `valid_values`.

Key: A key with the `catalog` area. Send `Idempotency-Key` and `Content-Type: application/json`.

Body:

- `product_id` (string (uuid), required)
- `technique_id` (string (uuid), required)
- `zone_ids` (array of string (uuid), required): 1 to 2 items.
- `quantity` (integer, required): 1 to 999.
- `carrier_id` (string (uuid))

Answer:

- `product_id` (string (uuid), required)
- `technique_id` (string (uuid), required)
- `zone_ids` (array of string (uuid), required)
- `quantity` (integer, required)
- `unit_cost` (object, required)
  - `net` (string, required)
  - `vat` (string, required)
  - `gross` (string, required)
  - `currency` (constant, required): Always `"SAR"`.
- `lines_total` (object, required)
  - `net` (string, required)
  - `vat` (string, required)
  - `gross` (string, required)
  - `currency` (constant, required): Always `"SAR"`.
- `shipping` (object, required)
  - `carrier_id` (string (uuid), required)
  - `fee` (object, required)
    - `net` (string, required)
    - `vat` (string, required)
    - `gross` (string, required)
    - `currency` (constant, required): Always `"SAR"`.
- `total` (object, required)
  - `net` (string, required)
  - `vat` (string, required)
  - `gross` (string, required)
  - `currency` (constant, required): Always `"SAR"`.
- `minimum_selling_price` (object, required)
  - `amount` (string, required)
  - `currency` (constant, required): Always `"SAR"`.

Errors: `unauthorized` (401), `area_forbidden` (403), `account_inactive` (403), `connection_disabled` (403), `invalid_request` (400), `idempotency_key_required` (400), `request_too_large` (413), `unsupported_media_type` (415), `rate_limited` (429), `internal_error` (500), `upstream_unavailable` (502), `api_unavailable` (503), `request_expired` (503), `service_unavailable` (503), `upstream_timeout` (504). See [Errors](https://docs.b7r.app/errors).

Request:

```bash
curl -X POST https://api.b7r.app/v1/quote \
  -H "Authorization: Bearer $B7R_API_KEY" \
  -H "Idempotency-Key: $(uuidgen 2>/dev/null || node -e 'console.log(crypto.randomUUID())')" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "8c2e4f6a-1b3d-4a5c-8e7f-9a0b1c2d3e4f",
    "technique_id": "2b9d6e1f-7a4c-4d8e-b3f5-0c1a2e3d4f5a",
    "zone_ids": [
      "5e7a9c1b-3d5f-4b7a-9c1e-2f4a6b8c0d2e"
    ],
    "quantity": 2,
    "carrier_id": "9b1d3f5a-7c9e-4b1d-8f5a-6c8e0a2b4d6f"
  }'
```

```javascript
const res = await fetch("https://api.b7r.app/v1/quote", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.B7R_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "product_id": "8c2e4f6a-1b3d-4a5c-8e7f-9a0b1c2d3e4f",
    "technique_id": "2b9d6e1f-7a4c-4d8e-b3f5-0c1a2e3d4f5a",
    "zone_ids": [
      "5e7a9c1b-3d5f-4b7a-9c1e-2f4a6b8c0d2e"
    ],
    "quantity": 2,
    "carrier_id": "9b1d3f5a-7c9e-4b1d-8f5a-6c8e0a2b4d6f"
  }),
});
const data = await res.json();
```

```python
import os, requests, uuid

res = requests.post(
    "https://api.b7r.app/v1/quote",
    headers={
        "Authorization": f"Bearer {os.environ['B7R_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "product_id": "8c2e4f6a-1b3d-4a5c-8e7f-9a0b1c2d3e4f",
        "technique_id": "2b9d6e1f-7a4c-4d8e-b3f5-0c1a2e3d4f5a",
        "zone_ids": [
            "5e7a9c1b-3d5f-4b7a-9c1e-2f4a6b8c0d2e"
        ],
        "quantity": 2,
        "carrier_id": "9b1d3f5a-7c9e-4b1d-8f5a-6c8e0a2b4d6f"
    },
    timeout=30,
)
data = res.json()
```

Answer (200 OK):

```json
{
  "product_id": "8c2e4f6a-1b3d-4a5c-8e7f-9a0b1c2d3e4f",
  "technique_id": "2b9d6e1f-7a4c-4d8e-b3f5-0c1a2e3d4f5a",
  "zone_ids": [
    "5e7a9c1b-3d5f-4b7a-9c1e-2f4a6b8c0d2e"
  ],
  "quantity": 2,
  "unit_cost": {
    "net": "45.00",
    "vat": "0.00",
    "gross": "45.00",
    "currency": "SAR"
  },
  "lines_total": {
    "net": "90.00",
    "vat": "0.00",
    "gross": "90.00",
    "currency": "SAR"
  },
  "shipping": {
    "carrier_id": "9b1d3f5a-7c9e-4b1d-8f5a-6c8e0a2b4d6f",
    "fee": {
      "net": "25.00",
      "vat": "0.00",
      "gross": "25.00",
      "currency": "SAR"
    }
  },
  "total": {
    "net": "115.00",
    "vat": "0.00",
    "gross": "115.00",
    "currency": "SAR"
  },
  "minimum_selling_price": {
    "amount": "59.00",
    "currency": "SAR"
  }
}
```

## Money: net, VAT and gross

Every amount B7R charges comes as an object: `net`, `vat` and `gross` as decimal strings with two places, and `currency`, always `SAR`. Read amounts as decimals, never as floating point numbers.

- Amounts are VAT inclusive: `gross` is what you pay.
- B7R is not VAT registered today, so `vat` is `"0.00"` and `net` equals `gross`.
- When B7R registers for VAT, the same fields carry the VAT inside `gross`: `vat` becomes more than zero and `net` is `gross` minus `vat`. Your code needs no change if it reads the three fields instead of working VAT out itself.
- Never assume a VAT rate. Every answer carries the figures that apply.

A charge today:

```json
{
  "net": "115.00",
  "vat": "0.00",
  "gross": "115.00",
  "currency": "SAR"
}
```

## Minimum selling price

`minimum_selling_price` is the lowest price you may sell the product for, per piece, worked out on the cost per piece (shipping is not part of it). It follows a markup over cost that B7R sets and can change, so read it from the catalog or a fresh quote, and never store it as a constant.
