Money & prices

Every money figure in the API has a field in one shape, the money value:

"total_amount_money": { "value": 18865, "currency": "USD", "decimal_places": 2, "display": "USD 188.65" }

Member	What it holds
`value`	An integer in minor units of `currency`: cents for USD, yen for JPY.
`currency`	The ISO 4217 code.
`decimal_places`	The scale of `value`. On every `*_money` field it is the ISO 4217 digits of `currency`: 2 for USD and EUR, 0 for JPY, 3 for KWD.
`display`	The same figure as a string ready to show: the currency code, a space, then the amount at `decimal_places`, e.g. `"USD 188.65"`.

All four members are always present. A figure the platform does not know is absent, never { "value": 0 } and never an empty currency, so treat a missing money field as “not known”, not as zero.

Where to read it

New integrations read money from three places, and all three carry the shape above:

*_money fields, beside the figure they replace: total_amount_money, price_money, max_amount_money, captured_total_money, and the rest in the migration table.
value inside objects that already carried an integer in minor units with its decimal_places, such as flight fares, select_ancillaries total_with_ancillaries and a booking’s confirmation.total_paid.
amount_money inside objects that hold money beside other members, such as a cancellation preview’s refund (which also carries basis) or a hotel tax line (which also carries description and included).

One rule covers all three:

value is an integer in minor units. Divide it by 10 ** decimal_places to get the amount, and show display when you need text.

value is not a display value. { "value": 15977, "decimal_places": 2 } is 159.77, not 15,977. Rendering value directly shows prices 100 times too high in a two-decimal currency. 15977 is a plausible long-haul fare, so a page of prices in the wrong unit can look like real data.

Convert it

type MoneyValue = {
  value: number          // integer, minor units
  currency: string       // ISO 4217
  decimal_places: number // scale of value
  display: string        // e.g. "USD 159.77"
}

// The amount in major units, for arithmetic you cannot do in integers.
function toMajor(money: MoneyValue): number {
  return money.value / 10 ** money.decimal_places
}

// A localized string. `display` is already a fixed "USD 159.77" form;
// use Intl when you want the reader's locale instead.
function formatMoney(money: MoneyValue, locale?: string): string {
  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency: money.currency,
    minimumFractionDigits: money.decimal_places,
    maximumFractionDigits: money.decimal_places,
  }).format(toMajor(money))
}

formatMoney({ value: 15977, currency: 'USD', decimal_places: 2, display: 'USD 159.77' }) // "$159.77"
formatMoney({ value: 18000, currency: 'JPY', decimal_places: 0, display: 'JPY 18000' })  // "¥18,000"

from decimal import Decimal

def to_major(money: dict) -> Decimal:
    # Decimal, not float: binary floats cannot represent every cent exactly.
    return Decimal(money["value"]) / (10 ** money["decimal_places"])

to_major({"value": 15977, "currency": "USD", "decimal_places": 2, "display": "USD 159.77"})
# Decimal('159.77')

Not every currency has 2 decimals

Currency	`decimal_places`	`value`	Amount
USD, EUR, GBP, most others	`2`	`15977`	159.77
JPY, KRW, VND, CLP	`0`	`18000`	18,000
BHD, JOD, KWD, OMR, TND	`3`	`159770`	159.770

Hardcoding / 100 shows JPY and KRW prices 100 times too small and Kuwaiti dinar prices 10 times too high. Divide by the decimal_places sent with the figure.

Objects that carry value without being a *_money field can use a scale other than the ISO digits. Cached flight prices converted from another currency are one case: a JPY fare can arrive as { "value": 1561500, "currency": "JPY", "decimal_places": 2 }, which is JPY 15,615. The rule does not change: divide by the decimal_places on the object, never by digits you look up from the currency code. On *_money fields decimal_places is always the ISO digits.

Arithmetic: sum before you divide

To total several prices, such as the legs of a trip or the items in it, add the integer values and convert once at the end. Converting each figure first introduces floating-point error that shows up as totals one cent off.

// Correct: integer arithmetic, one conversion at the end.
const dp = items[0].price_money.decimal_places
const totalMinor = items.reduce((sum, i) => sum + i.price_money.value, 0)
const total = totalMinor / 10 ** dp

// Wrong: 0.1 + 0.2 !== 0.3
const total = items.reduce((sum, i) => sum + i.price_money.value / 100, 0)

Only add figures that share both currency and decimal_places. One response can hold more than one currency, for example a trip with a flight and a hotel priced by different providers. A trip whose items are priced in more than one currency has no totals.total_money on POST /v1/trip, for the same reason.

Fields that need more than the rule

Hotel cancellation steps

A step in a hotel cancellation_schedule (on hotel_search rates and on a quoted item’s hotel_terms) states the charge in one of three ways, and each has its own field:

`type`	Field to read	Example
`amount`, `flat_fee`	`amount_money`	`{ "value": 60613, "currency": "EUR", "decimal_places": 2, "display": "EUR 606.13" }`
`percent`, `percentage`	`percent`, a percentage of the stay price	`50`
`nights`	`nights`, a number of nights of the stay	`1`

The deprecated amount on a step held any of the three, so it was a sum, a percentage or a count depending on type. Read the field that matches the step instead.

Paying with a Shared Payment Token

agent_spt_params.max_amount_money on the checkout response is the limit to scope the token to. Pass max_amount_money.value (minor units) and max_amount_money.currency to the token mint. The sandbox walkthrough shows the calls.

Committing a cancellation or refund

hotel_cancel_commit and flight_refund_commit take acknowledged, the refund the customer was shown on the preview. Copy the preview’s refund.amount_money into it unchanged:

{
  "booking_ref": "JNK-H1ZK90",
  "last_name": "Doe",
  "quote_id": "svq_01J7ZR3M8FKX2P9C",
  "acknowledged": { "value": 25000, "currency": "USD", "decimal_places": 2, "display": "USD 250.00" }
}

The platform compares value, currency and decimal_places against the refund as it stands and ignores the other members. A figure that does not match is refused with 409 quote_drift and a fresh quote, and nothing is cancelled. Copy the object as it arrived; do not recompute or rescale it. The older form, the inline value, currency and decimal_places of refund itself, is still accepted. A flight refund preview that names no refund figure (a MANUAL_REQUIRED refund whose penalty is unknown) has nothing to acknowledge: commit it with manual_ok: true and without acknowledged.

What a booking was charged

booking.total_paid on get_booking is the gross amount captured for the booking: the original payment plus any later collections, such as the difference paid on an exchange. Refunds are not subtracted from it. It is absent in exactly two cases: nothing has been captured yet, or the booking was charged in more than one currency. If the captured amount cannot be read, get_booking returns an error rather than omitting the field, so an absent total_paid never means “unknown”.

Webhooks

Webhook payloads carry the same shape. booking.partial has data.items[].captured_amount_money and data.captured_total_money, and servicing.completed has data.refund and data.penalty. See Webhooks.

Using the CLI or SDK?

@gojinko/cli output (JSON is its default format) and @gojinko/api-client responses are the raw API body: neither converts money. The *_money fields appear in their output exactly as described on this page.

Prices look 100 times too high?

That symptom has one common cause: value was shown without dividing by 10 ** decimal_places. Check the raw JSON. If a fare you expect to be about $160 reads "value": 15977, "decimal_places": 2, show display or divide. Prices 100 times too small usually mean a hardcoded / 100 applied to a currency with decimal_places: 0, such as JPY.

Older fields

Before contract 0.26.0 the API returned money in several shapes, and some of them were in major units. Those fields are still sent, unchanged, beside their replacements. They are marked deprecated in the OpenAPI document, and no removal date is set yet. When one is set, it will be announced as described in Versioning & deprecation. New code reads the fields described above; this section is for code that still reads the older ones.

How to read the older shapes

The older fields follow a two-scale rule:

If the money object carries decimal_places, its number is an integer in minor units, whether it is named value or amount: divide by 10 ** decimal_places. If it has no decimal_places, amount is already in major units.

Apply the rule to the object in the response you received. The schemas mark decimal_places as optional on the shared Money shape, so generated types show it as optional even on endpoints that always send it.

Older shape	Where	Scale
`{ amount, currency, decimal_places }`	`select_ancillaries` `total_with_ancillaries`, payment attempt `money.*`, `get_booking` `confirmation.total_paid` and `refund_status.refunded_amount`	Minor units. `value` now carries the same integer.
`{ amount, currency }` without `decimal_places`	Trip, checkout and book `total_amount`, item `price`, `original_price`, `price_change.*`, `available_ancillaries[].price_per_unit`	Major units, e.g. `188.65`.
A bare number beside `currency` and a `*_display` string	`POST /v1/trip` `items[].price` and `totals.total`; `hotel_search` `rates[].total_amount`, `taxes_breakdown[].amount`, `cancellation_schedule[].amount`, `budget_filter.max_budget_per_night`	Major units.
An integer without `decimal_places`	`agent_spt_params.max_amount`; car `get_booking` `*_minor` fields	Minor units, with no scale stated.
`{ amount, currency }` in a webhook	`booking.partial` `captured_amount`, `captured_total`	Major units.
`value`, `currency`, `decimal_places` inline beside other members	Cancellation and refund `refund`, `penalty`, `refund_due`, `refunded`, `money`	Minor units. `amount_money` now carries the same figure at the ISO digits.

Field-by-field migration

Each older field below stays in the response. So does a currency or *_display sibling that only described it. The replacement is a money value unless the row says otherwise. Trip, checkout and payment

Endpoint	Older field	Read instead
`POST /v1/trip`	`items[].price`, `items[].currency`, `items[].price_display`	`items[].price_money`
`POST /v1/trip`	`totals.total`, `totals.currency`, `totals.total_display`	`totals.total_money` (absent when the items are priced in more than one currency)
`GET /v1/trip/{trip_id}`, checkout, book	`total_amount`	`total_amount_money`
`GET /v1/trip/{trip_id}`, ancillaries, checkout, book	`items[].price`	`items[].price_money`
same	`items[].original_price`	`items[].original_price_money`
same	`items[].price_change.original`, `.current`, `.delta`	`items[].price_change.original_money`, `.current_money`, `.delta_money` (`delta_money.value` is signed)
same	`items[].available_ancillaries[].price_per_unit`	`items[].available_ancillaries[].price_per_unit_money`
same	`items[].hotel_terms.taxes_breakdown[].amount`, `.currency`, `.display`	`items[].hotel_terms.taxes_breakdown[].amount_money`
same	`items[].hotel_terms.cancellation_schedule[].amount`, `.currency`, `.display`	`amount_money`, `percent` or `nights` on the step, as `type` says
`POST /v1/select_ancillaries`	`total_with_ancillaries.amount`	`total_with_ancillaries.value` (same integer)
checkout, book	`agent_spt_params.max_amount`, `agent_spt_params.currency`	`agent_spt_params.max_amount_money`
`GET /v1/trip/{trip_id}`, payment attempts, `POST /v1/agent_payment/submit`	payment attempt `money.authorized`, `.captured`, `.released`, `.refunded`, `.externally_reimbursed`: `amount`	`value` in the same object (same integer)

Hotels

Endpoint	Older field	Read instead
`hotel_search`	`hotels[].rooms[].rates[].total_amount`, `.currency`, `.total_amount_display`	`rates[].total_amount_money`
`hotel_search`	`rates[].taxes_breakdown[].amount`, `.currency`, `.display`	`rates[].taxes_breakdown[].amount_money`
`hotel_search`	`rates[].cancellation_schedule[].amount`, `.currency`, `.display`	`amount_money`, `percent` or `nights` on the step
`hotel_search`	`budget_filter.max_budget_per_night`, `budget_filter.currency`	`budget_filter.max_budget_per_night_money` (absent when the request named no currency)
`hotel_search`	`rooms[].max_occupancy`	`rooms[].room_capacity`, how many people the room sleeps. `max_occupancy` here repeats `requested_occupancy` and never was the room’s capacity. Not a money field.
`hotel_details`	`rooms[].max_occupancy`	`rooms[].room_capacity` (the same catalogue figure). Not a money field.

hotel_search nearby_alternatives[] carries the same rate fields as hotels[], with the same replacements. Post-booking

Endpoint	Older field	Read instead
`get_booking`	`booking.items[].confirmation.total_paid.amount`	`booking.items[].confirmation.total_paid.value` (same integer)
`get_booking`	(none: declared before, never sent)	`booking.total_paid`, see What a booking was charged
`get_booking`	`booking.refund_status.refunded_amount.amount`	`booking.refund_status.refunded_amount.value` (same integer)
`get_booking`	`items[].servicing.cancellation.refund_due`: inline `value`, `currency`, `decimal_places`	`items[].servicing.cancellation.refund_due.amount_money`
`get_booking`	`items[].servicing.cancellation.refunded`: inline figure	`items[].servicing.cancellation.refunded.amount_money`
`get_booking` (car)	`items[].cancellation.monetary_refund_minor`, `.voucher_refund_minor`, `.fee_minor`	`items[].cancellation.monetary_refund_money`, `.voucher_refund_money`, `.fee_money`
`get_booking` (car)	`items[].exchange.delta_amount_minor`, `.new_total_minor`	`items[].exchange.delta_amount_money`, `.new_total_money`
`hotel_cancel_preview`	`refund`: inline figure	`refund.amount_money`
`hotel_cancel_preview`	`penalty`: inline figure	`penalty.amount_money` (absent when `fee_known` is false)
`flight_refund_preview`	`refund`, `penalty`: inline figure	`refund.amount_money`, `penalty.amount_money` (the penalty’s is absent when the fee is not known)
`hotel_cancel_status`, `flight_refund_status`	`money`: inline figure	`money.amount_money`
`hotel_cancel_commit`, `flight_refund_commit` (request)	`acknowledged` built from the inline `refund` figure	`acknowledged` copied from `refund.amount_money`. Both are accepted.

Webhooks

Event	Older field	Read instead
`booking.partial`	`data.items[].captured_amount` (major units)	`data.items[].captured_amount_money`
`booking.partial`	`data.captured_total` (major units)	`data.captured_total_money`

Not a money field: POST /v1/trip item kind

Endpoint	Older field	Read instead
`POST /v1/trip`	`items[].type`	`items[].kind`, the same value and the same field name `GET /v1/trip/{trip_id}` and checkout use

Fields already in the money-value shape, such as flight fare total_price, get_booking servicing_summary[] and car search amounts, have no replacement and are not deprecated.

Getting started

Guides

Marketing claim

Authentication

Connect

Developer Platform

Concepts

Where to read it

Convert it

Not every currency has 2 decimals

Arithmetic: sum before you divide

Fields that need more than the rule

Hotel cancellation steps

Paying with a Shared Payment Token

Committing a cancellation or refund

What a booking was charged

Webhooks

Using the CLI or SDK?

Prices look 100 times too high?

Older fields

How to read the older shapes

Field-by-field migration

​Where to read it

​Convert it

​Not every currency has 2 decimals

​Arithmetic: sum before you divide

​Fields that need more than the rule

​Hotel cancellation steps

​Paying with a Shared Payment Token

​Committing a cancellation or refund

​What a booking was charged

​Webhooks

​Using the CLI or SDK?

​Prices look 100 times too high?

​Older fields

​How to read the older shapes

​Field-by-field migration

Where to read it

Convert it

Not every currency has 2 decimals

Arithmetic: sum before you divide

Fields that need more than the rule

Hotel cancellation steps

Paying with a Shared Payment Token

Committing a cancellation or refund

What a booking was charged

Webhooks

Using the CLI or SDK?

Prices look 100 times too high?

Older fields

How to read the older shapes

Field-by-field migration