# eSIM pricing

> What each eSIM price field means, what is debited from your balance and how the commission is read.

Source: https://fx-port.com/docs/esims/pricing

Every eSIM package and topup package carries a set of money fields, computed on the server in your
agency's currency. Any pricing sent in a request body is ignored: every order creates one eSIM at the
price the server computes.

The same word means different amounts in different endpoints. Read this page once, then use the table
[at the end](#what-price-means-in-each-response) when you are unsure.

## Field meanings

These are the fields of a package in `GET /api/v1/esims/packages`:

| Field | Meaning |
|---|---|
| `base_price` | The **base price** of the package in your agency currency, before your commission. It is **not** the amount debited from your balance. `price` carries the same value (the legacy name: in the catalog `price` is the base price, while in orders and topup packages it is the retail price, which is why `base_price` is the name to use) |
| `retail_price` / `total_price` | The price to charge the traveler, in your agency currency. Both fields have the same value; it includes your commission |
| `balance_debit_amount` | **The amount debited from your agency balance** when you order the package (live). Read this field: do not compute it from `base_price`. `b2b_price` carries the same value (the name flights and hotels use) |
| `agency_commission` | Your commission **rate**, as text: `"12 %"` in the examples, `"0 %"` for contracted corporate agencies. In bookings it is an **amount** (see below) |
| `commission_rate` | The same rate as a **number**: `12` in the examples, `0` for contracted corporate agencies. Use it when you compute |
| `currency` | Your agency's settlement currency: the currency of every amount |
| `supplier_currency` | The currency the supplier prices the package in (for example `"USD"`) |
| `exchange_rate` | The rate `supplier_currency` → `currency` used for this package |

## What is debited from your balance

The amount debited when you order a package is **`balance_debit_amount`**. Your commission is what is
left of the retail price:

~~~
commission  = total_price − balance_debit_amount
~~~

`balance_debit_amount` can be **higher than `base_price`**: amounts that are specific to your agency are part of
what is debited, so the relation between `base_price` and the other amounts differs from agency to agency. Your
commission is the rate of `agency_commission` applied to `balance_debit_amount`, rounded up to the cent
(`12 %` of `418.60` is `50.232`, shown as `50.24`). Never rebuild `balance_debit_amount` or `total_price`
from `base_price`: read them.

**Example** (a sandbox agency that settles in `DZD`, supplier currency `USD`, package `france-in-7days-1gb`):

~~~json
{
  "price": 402.5,
  "base_price": 402.5,
  "retail_price": 468.84,
  "total_price": 468.84,
  "balance_debit_amount": 418.6,
  "b2b_price": 418.6,
  "agency_commission": "12 %",
  "commission_rate": 12,
  "currency": "DZD",
  "supplier_currency": "USD",
  "exchange_rate": 250.0
}
~~~

Check: `468.84 − 418.60 = 50.24`, the commission. After the order, the booking of this eSIM has
`total_price: 468.84` and `agency_commission: 50.24` (an amount), and the
[account history](https://fx-port.com/docs/account/history.md) shows `netPrice: 418.6` (twin `b2b_price`), the amount that was debited.


> [!NOTE]
> A contracted corporate agency has `agency_commission` `"0 %"`: `total_price` and `balance_debit_amount`
> are then equal.


## What `price` means in each response

| Response | `price` | Where the other amounts are |
|---|---|---|
| `GET /esims/packages` | Base price, **before** your commission (`base_price` has the same value) | `total_price` / `retail_price`, `balance_debit_amount` / `b2b_price` |
| `GET /esims/topup-packages/{iccid}` | The **retail** price: same as `total_price` | `base_price` is the base price (what `price` is in the catalog), `commission` is your commission as an **amount**, `balance_debit_amount` / `b2b_price` is the debit |
| `POST /esims/orders`, `POST /esims/topups`, setup instructions | The **retail** price the traveler pays: same as `total_price` | `currency`, `agency_currency`, `supplier_currency`, `exchange_rate` |
| `GET /esims/bookings`, topup history | No `price` | `total_price`, and `agency_commission` as an **amount** |
| [Account history and booking detail](https://fx-port.com/docs/account/history.md) | No `price` | `totalPrice`, `agencyCommission` (amount) and `netPrice`, the amount debited. Their twins are `total_price`, `agency_commission` and `b2b_price` |

Two consequences:

- `agency_commission` is a **rate string** (`"12 %"`) in the catalogs, with the number `commission_rate` next to it, and an **amount** (`50.24`) in bookings
  and in the account endpoints.
- A topup package's `price` is **not** comparable with the `price` of a catalog package: compare `base_price`
  with `base_price`, or `total_price` with `total_price`. Use `base_price` and `total_price` everywhere and the
  ambiguity disappears.

## Supplier currency

FX-Port sources eSIM packages from its supplier network, and each supplier settles in its own currency
(configured per supplier on the FX-Port side — not hard-coded). `exchange_rate` is always
`supplier_currency → currency`, never assumed to be USD. If a package's `supplier_currency` already
matches your agency `currency`, `exchange_rate` is `1.0`. Every amount you read is already converted: you
never convert yourself.

## Order and topup responses

`POST /api/v1/esims/orders` and `POST /api/v1/esims/topups` return the pricing block nested under
`data.order` / `data.topup` as `price`, `total_price`, `retail_price`, `currency`, `agency_currency`,
`supplier_currency` and `exchange_rate`. The supplier's own cost is not part of a response. A topup adds a
`balance` block with `previous` and `current`, the agency balance in the order's currency before and after the
debit; in the sandbox both are `0.0` because nothing is debited.