Hoppa till huvudinnehåll

Amounts in minor units

2026-11-14 · Breaking change · Upcoming: not yet in production

Amounts are whole numbers in the minor unit of the currency, with the same field names: every currency has 2 decimals, so 422.44 is 42244 and ISK 1 250 is 125000.

What changed

  • This holds for every amount in every request and response:
    • unitPrice of POST /api/v1/orders and POST /api/v1/orders/{id}/lines;
    • the order, line and pricing amounts of GET /api/v1/orders/{id} and totalAmount of GET /api/v1/orders;
    • the statistics of /stats/summary, /stats/trends and /stats/top-articles;
    • data.unitPrice and data.lineTotal of order.line_added in the order timeline and in the order.line_added webhook (data.unit_price, data.line_total), including stored history, which was converted;
    • parameters.minAmount of a MinOrderAmount rule in GET /api/v1/orders/validation-rules, which returns {"minAmount": 50000} for 500.00 (stored rules were converted);
    • and the detail of 422 https://orderex.io/problems/order-status-change-rejected when that rule rejects a status change, which names minor units, such as Order total amount 49999 is below the minimum required 50000 (minor units).
  • Percent fields (discountPercent, vatRate, percentage) are unchanged.
  • An amount that is not a whole number (422.44, 42244.0, 4.2244e4) or does not fit in a 64-bit integer is rejected with 422 https://orderex.io/problems/invalid-amount and errors naming the field, such as errors["lines[0].unitPrice"], and nothing is written.
  • An amount sent as a JSON string ("42244"), which was read as a number before, is now rejected with 400 https://orderex.io/problems/invalid-request.
  • Averages (averageOrderValue) are rounded once to a whole minor unit away from zero (100.5 is 101), and /stats/trends gets totals for the whole period.
  • A retry with an Idempotency-Key first used with major units before this change gives 409 https://orderex.io/problems/idempotency-key-reused when you send the body in minor units, or 422 https://orderex.io/problems/invalid-amount when it still has an amount with decimals; use a new key for a create you converted.
  • Note that a webhook retry after the change can carry minor units where the first attempt carried major units, with the same id.

Affected operations

  • POST /api/v1/orders
  • POST /api/v1/orders/{id}/lines
  • GET /api/v1/orders/{id}
  • GET /api/v1/orders
  • GET /api/v1/orders/stats/summary, GET /api/v1/orders/stats/trends and GET /api/v1/orders/stats/top-articles
  • GET /api/v1/orders/{id}/timeline
  • GET /api/v1/orders/validation-rules
  • PATCH /api/v1/orders/{id}/status, whose 422 order-status-change-rejected names minor units
  • The webhook order.line_added

What you do

  • Multiply every amount you send by 100 and divide every amount you read by 100 when you show it in major units.

How breaking changes are announced and how long a deprecated endpoint stays: see the versioning policy.