Skip to content
Maple

    Core concepts

    Money and amounts

    Every amount in the API is an integer in the currency’s minor units. No floats, no rounding surprises.

    Every monetary value in the Developer API is an integer in the currency’s minor units — cents for USD. There are no decimals and no floating-point amounts anywhere in the API.

    450  =  $4.50      (USD, 2 minor-unit digits)

    This is deliberate: representing money as integers avoids the rounding errors that come from floating-point math, so the total you read is exactly the total the customer was charged.

    In orders

    On the order resource, every amount is an integer in USD cents, and totals.currency tells you the currency:

    "totals": {
      "currency": "USD",
      "subtotal": 525,
      "tax": 42,
      "surcharge": 0,
      "tip": 0,
      "delivery_fee": 0,
      "delivery_tip": 0,
      "total": 567
    }

    Line items follow the same rule: base_price (per unit, before modifiers), tax, and each modifier’s price change are all integer cents.

    In menus

    When you publish a menu, prices are an amount object that pairs the integer with its currency:

    { "amount": { "amountMinor": 450, "currency": "USD" } }

    amountMinor is the integer in the currency’s smallest unit, and currency is the uppercase ISO‑4217 code (USD). For USD that’s cents — send integer cents and you’re done.

    For reference, minor-unit digits vary by currency — the model is built to handle this once multi-currency lands:

    Currency Minor-unit digits amountMinor for 5 units
    USD 2 500 ($5.00)
    JPY 0 5 (¥5)
    KWD 3 5000 (KD 5.000)

    Rounding

    Because every amount is an integer, there’s no rounding in transit — the number you read is exact. Rounding only happens when Maple derives a new amount, such as a percentage discount or a tax line. The default is banker’s rounding (round half to even), which avoids the upward bias of always rounding .5 up.

    You can override it per currency through the currency profile’s rounding mode, but half-even is the default — assume it when you reconcile totals on your side.

    Formatting for display

    To show an amount, divide by 10 raised to the currency’s minor-unit digits:

    function format(amountMinor: number, currency: string, digits = 2): string {
      return new Intl.NumberFormat('en-US', { style: 'currency', currency }).format(amountMinor / 10 ** digits);
    }
    

    format(567, 'USD'); // "$5.67"

    Don’t hardcode division by 100 if you handle currencies with a different exponent — drive it off the currency.