Amounts & Currencies

Every monetary value in the API is an integer in the smallest unit of the store’s currency. There are no decimal points and no human-formatted strings like "$12.34" or "Rp 5.000".

{
  "currency": "USD",
  "total_amount": 1234   // = $12.34
}

Integers avoid floating-point rounding errors and keep every amount exact. The catch: an integer alone is ambiguous — you must know how many decimal places the currency has to turn it into a human amount. That number varies by currency, and there is no universal standard, which is the most common source of confusion.

Always read an amount together with its currency. Amounts live on resources next to a currency code: a store has store.currency, an order has order.currency. Products and inventory items inherit the store currency.

Minor units per currency

The “smallest unit” is the currency’s minor unit. Most currencies split into 100 (cents, pence, sen), but many do not.

Decimals	Multiplier	Currencies	Example
2 (default)	×100	USD, EUR, GBP, SGD, MYR, and most others	`1234` → $12.34
0 (no minor unit)	×1	IDR, JPY, KRW, VND, CLP, XAF, XOF, and others below	`5000` → Rp 5,000
3	×1000	BHD, JOD, KWD, OMR, TND	`1234` → BD 1.234

Zero-decimal currencies (the integer is the amount — do not multiply by 100): BIF, CLP, DJF, GNF, IDR, IQD, JPY, KMF, KRW, MGA, PYG, RWF, UGX, VND, VUV, XAF, XOF, XPF. Three-decimal currencies: BHD, JOD, KWD, OMR, TND. Every other currency uses 2 decimals.

For a store using IDR (Indonesian Rupiah), a price of 5000 means Rp 5,000 — not Rp 50. Rupiah has no minor unit, so the integer is the whole-rupiah amount. Sending 500000 when you mean Rp 5,000 overcharges the customer 100×.

Converting to and from human amounts

Let d be the number of decimals for the currency (from the table above):

human amount  = minor_units / 10^d
minor units   = round(human_amount * 10^d)

// Decimals per currency. Only non-2 currencies are listed; everything else is 2.
const CURRENCY_DECIMALS: Record<string, number> = {
  BIF: 0, CLP: 0, DJF: 0, GNF: 0, IDR: 0, IQD: 0, JPY: 0, KMF: 0, KRW: 0,
  MGA: 0, PYG: 0, RWF: 0, UGX: 0, VND: 0, VUV: 0, XAF: 0, XOF: 0, XPF: 0,
  BHD: 3, JOD: 3, KWD: 3, OMR: 3, TND: 3,
};

const decimals = (currency: string) => CURRENCY_DECIMALS[currency] ?? 2;

// API integer -> human amount
const toHuman = (minor: number, currency: string) =>
  minor / 10 ** decimals(currency);

// human amount -> API integer (use when sending prices/amounts)
const toMinor = (human: number, currency: string) =>
  Math.round(human * 10 ** decimals(currency));

toHuman(1234, "USD"); // 12.34
toHuman(5000, "IDR"); // 5000
toMinor(12.34, "USD"); // 1234
toMinor(5000, "IDR");  // 5000

For display, Intl.NumberFormat reads the correct decimals from the currency for you:

new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" })
  .format(toHuman(1234, "USD")); // "$12.34"
new Intl.NumberFormat("en-US", { style: "currency", currency: "IDR" })
  .format(toHuman(5000, "IDR")); // "IDR 5,000.00"

Amount fields in the API

Every field below is an integer in the store currency’s minor units.

Products & inventory items

Field	Meaning
`price`	Current selling price
`original_price`	Price before discount (strike-through)
`cost`	Merchant’s unit cost (present only when cost tracking is enabled)

Product variants carry the same three fields.

Orders

Field	Meaning
`items_amount`	Sum of line items before adjustments
`answers_amount`	Total from priced order-form answers
`discounts_amount`	Total discounts applied
`service_amount`	Selected service (e.g. delivery) charge
`service_charge_amount`	Store service charge
`tax_amount`	Tax total
`tip_amount`	Tip
`adjustment_amount`	Manual adjustment (can be negative)
`total_before_tax`	Subtotal before tax
`total_amount`	Final amount payable

Nested amounts: each discounts[].amount, each line item’s price and total_amount, line-item option prices[], and the selected service.price.

Store

Field	Meaning
`service_charge.amount`	Default service charge configured for the store

Merchant API V2

Products

Customers

Orders

Inventory

Messages

Webhooks

Minor units per currency

Converting to and from human amounts

Amount fields in the API

Products & inventory items

Orders

Store

​Minor units per currency

​Converting to and from human amounts

​Amount fields in the API

​Products & inventory items

​Orders

​Store

Minor units per currency

Converting to and from human amounts

Amount fields in the API

Products & inventory items

Orders

Store