> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maple.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# 金额

> API 中的每个金额都是以货币最小单位表示的整数。没有浮点数，没有舍入意外。

Developer API 中的每个货币值都是**以货币最小单位表示的整数** — 美元为美分。API 中任何地方都没有小数，也没有浮点金额。

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

这是有意为之：用整数表示金额可避免浮点运算带来的舍入误差，因此您读取到的总额与顾客被扣除的总额完全一致。

## 订单中

在订单资源上，每个金额都是以美分表示的整数，`totals.currency` 告诉您货币：

```json theme={null}
"totals": {
  "currency": "USD",
  "subtotal": 525,
  "tax": 42,
  "surcharge": 0,
  "tip": 0,
  "delivery_fee": 0,
  "delivery_tip": 0,
  "total": 567
}
```

行项目遵循同样的规则：`base_price`（每件单价，不含加料选项）、`tax` 以及每个加料选项的 `price` 变动，都是整数美分。

<Info>
  **总额由 Maple 计算，并以此为准。** `total` 等于 subtotal + tax + surcharge + tip + delivery fees。您无需重新计算面向顾客的价格 — 直接读取即可。请参阅[Maple 如何运作](/zh/developer-api/how-maple-works)。
</Info>

## 菜单中

发布菜单时，价格是一个 `amount` 对象，将整数与其货币配对：

```json theme={null}
{ "amount": { "amountMinor": 450, "currency": "USD" } }
```

`amountMinor` 是以货币最小单位表示的整数，`currency` 是大写的 ISO‑4217 代码（`USD`）。对于美元，就是美分 — 发送整数美分即可。

<Note>
  **多币种功能正在开发中。** 目前 Developer API 仅支持 **USD**：请以 `USD` 发布菜单，订单总额也以 `USD` 返回。菜单模型已接受非 USD 金额和按币种的配置（菜单的 `currencies` 集合，每种货币有各自的最小单位位数和舍入方式），但通过订单流程应用多币种定价即将推出。目前请按 USD 开发。
</Note>

供参考，不同货币的最小单位位数各不相同 — 多币种上线后，模型即可处理这种差异：

| 货币 | 最小单位位数 | 5 个单位的 `amountMinor` |
| - | - | - |
| USD | 2 | `500` (\$5.00) |
| JPY | 0 | `5` (¥5) |
| KWD | 3 | `5000` (KD 5.000) |

## 舍入

由于每个金额都是整数，传输过程中不存在舍入 — 您读取的数字是精确的。只有当 Maple 推导出新金额时才会发生舍入，例如百分比折扣或税费行。默认采用**银行家舍入**（四舍六入五成双），避免总是将 `.5` 进位带来的向上偏差。

您可以通过货币配置的舍入模式按币种覆盖，但默认是 half-even — 在您这一侧核对总额时请以此为准。

## 格式化显示

要显示金额，请除以 10 的“货币最小单位位数”次方：

```ts theme={null}
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"
```

如果您处理的货币指数不同，请不要硬编码除以 100 — 应根据货币来决定。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.