eSIM pricing
What each eSIM price field means, what is debited from your balance and how the commission is read.
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 when you are unsure.
Field meanings
These are the fields of a package in GET /:
| 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_amountbalance_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):
{
"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 shows netPrice: 418.6 (twin b2b_price), the amount that was debited.
What price means in each response
| Response | price | Where the other amounts are |
|---|---|---|
GET / | Base price, before your commission (base_price has the same value) | total_price / retail_price, balance_debit_amount / b2b_price |
GET / | 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 /, POST /, setup instructions | The retail price the traveler pays: same as total_price | currency, agency_currency, supplier_currency, exchange_rate |
GET /, topup history | No price | total_price, and agency_commission as an amount |
| Account history and booking detail | No price | totalPrice, agencyCommission (amount) and netPrice, the amount debited. Their twins are total_price, agency_commission and b2b_price |
Two consequences:
agency_commissionis a rate string ("12 %") in the catalogs, with the numbercommission_ratenext to it, and an amount (50.24) in bookings and in the account endpoints.- A topup package's
priceis not comparable with thepriceof a catalog package: comparebase_pricewithbase_price, ortotal_pricewithtotal_price. Usebase_priceandtotal_priceeverywhere 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 / and POST / 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.