Money

Every monetary value on this API is an integer in the currency’s minor unit, paired with an ISO 4217 currency code. No field anywhere accepts a decimal.

{
  "amount": 1999,
  "currency": "usd"
}

That is 19.99 USD.

Sending 19.99 does not create a $19.99 charge. It is refused, because the field is an integer. Sending 19 creates a 19 cent charge, which is accepted and wrong. This is the most expensive mistake available in a new integration.

Why integers

Binary floating point cannot represent most decimal fractions exactly. 0.1 + 0.2 is 0.30000000000000004 in every IEEE 754 language, which is every language you are likely to be calling from. For money that is not a rounding curiosity. Sum a few thousand order lines in floats and your total disagrees with the sum of the same lines computed anywhere else, including in your accounting system. Integer minor units make every amount exact and every sum reproducible.

Converting

Multiply by the currency’s exponent when sending, divide when displaying. Do the division only at the point of display, never in the middle of a calculation.

// to send
const minor = Math.round(19.99 * 100)   // 1999

// to display
const display = (1999 / 100).toFixed(2) // "19.99"

from decimal import Decimal

# to send
minor = int(Decimal("19.99") * 100)      # 1999

# to display
display = f"{Decimal(1999) / 100:.2f}"   # "19.99"

// to send
minor := int64(1999)

// to display
display := fmt.Sprintf("%d.%02d", minor/100, minor%100) // "19.99"

// to send
$minor = (int) round(19.99 * 100);        // 1999

// to display
$display = number_format($minor / 100, 2); // "19.99"

In Python use Decimal("19.99"), not 19.99. int(19.99 * 100) is 1998, because the float is slightly below 19.99 and int() truncates rather than rounds.

Not every currency has two decimals

Assuming a factor of 100 everywhere is wrong for 23 active currencies.

Zero-decimal currencies

The amount is the whole unit. 5000 in JPY is ¥5,000, not ¥50.

BIF  CLP  DJF  GNF  ISK  JPY  KMF  KRW
PYG  RWF  UGX  VND  VUV  XAF  XOF  XPF

Three-decimal currencies

The factor is 1000. 1999 in KWD is 1.999 KWD, not 19.99.

BHD  IQD  JOD  KWD  LYD  OMR  TND

Everything else

Two decimals, factor 100. USD, EUR, GBP, INR and the rest.

If you sell in JPY and hardcode a factor of 100, every amount you send is 100 times too small and every amount you display is 100 times too large. Read the exponent from the currency code rather than assuming it.

Currency codes

Send the ISO 4217 alphabetic code. Case is not significant on input, so usd and USD are both accepted. A code that is not an active ISO 4217 currency is refused:

{
  "error": {
    "code": "invalid_currency",
    "message": "not a valid iso 4217 currency code"
  }
}

Three ASCII letters is not a currency. ?currency=yen is refused rather than treated as an unknown code and relabelled onto a price that was never converted, which would show a shopper a dollar amount with a yen label on it.

Totals are computed server side

When you create or modify a cart or an order, the totals in the response are recomputed by the server in integer minor units, with tax applied to the discounted base. Do not compute a total client side and send it. Use the total the API returns. This is also what guarantees that the amount charged equals the total the shopper saw.

Negative amounts

Refunds, credits and adjustments carry the sign in the amount. Read the sign rather than inferring direction from the endpoint you called.

Get started

Essentials

Authentication

Make requests

Error handling

Why integers

Converting

Not every currency has two decimals

Zero-decimal currencies

Three-decimal currencies

Everything else

Currency codes

Totals are computed server side

Negative amounts

​Why integers

​Converting

​Not every currency has two decimals

​Zero-decimal currencies

​Three-decimal currencies

​Everything else

​Currency codes

​Totals are computed server side

​Negative amounts

Why integers

Converting

Not every currency has two decimals

Zero-decimal currencies

Three-decimal currencies

Everything else

Currency codes

Totals are computed server side

Negative amounts