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

# 批量购买

一次 `purchaseGiftCard` 调用只会购买**且仅购买一张**礼品卡，针对**一个优惠**并按**一个费率**。没有 `quantity` 字段，单次调用也不会在多个优惠或费率之间拆分。要购买多张卡，请多次发送该变更请求——每张卡一次调用，并为每次调用提供其各自唯一的 `idempotencyKey`。

每次调用如何选择其优惠与费率，取决于你是传入 `offerId` 还是 `merchantSlug`。

### 购买流程一览

![](https://files.readme.io/bf6ad80159ab3e0beecb76d51f498a4093b793bf7368288abe62e5c81b2b36c5-diagram.svg)

### `offerId` — 锁定特定优惠与费率

当你传入 `offerId` 时，购买将锁定到该精确优惠及其费率。如果该优惠无法再履约（例如，按库存跟踪且已售罄的优惠），调用将**失败**——它**不会**静默替换为其他优惠。参见下方的缺货错误。

### `merchantSlug` — 自动选择最佳可用优惠

当你传入 `merchantSlug`（且不传 `offerId`）时，系统会在**每次调用发生的当下**为该商户选择**最佳的、当前有库存的优惠**。由于选择是按调用逐次进行的，对同一商户的重复购买可能会随着可用性变化而对应到**不同的优惠**。

### 固定额与可变额优惠及库存

* **固定面额优惠**会按面额进行库存跟踪。一旦某个面额售罄，将不再可选，任何进一步通过 `offerId` 固定到该面额的调用都会返回缺货错误。
* **可变额优惠**并不以相同方式受库存限制。它们通常保持可用，并在固定/有库存的优惠售罄时充当后备。可变额优惠往往具有与其替代的固定优惠**不同（通常更低）的奖励费率**。

> 📘 当你购买的卡数超过库存时会发生什么
>
> 假设某商户的最佳优惠是一个固定、按库存跟踪的优惠，只剩下**8**个库存，而你想要**10**张卡（即 10 次单独的 `purchaseGiftCard` 调用）：
>
> * **使用** `offerId`（固定到该固定优惠）：前 8 次调用成功；第 9 次和第 10 次调用因缺货错误而**失败**。不会自动回退到其他优惠或费率。
> * **使用** `merchantSlug`（自动选择）：前 8 次调用会按该固定优惠购买；一旦其售罄，其余调用将自动选择**下一个最佳可用优惠**——这可能是**奖励费率更低的可变额优惠**。
>
> 在所有情况下，每张卡都会以该次调用所解析到的优惠与费率原子性地完成购买——不存在混合或部分履约的订单。

### 使用 `minRewardRate` 保护你的费率

当你使用 `merchantSlug` 购买时，使用 `minRewardRate` 设置奖励费率下限。购买前，系统会检查该商户在所选金额与支付方式下可提供的最佳费率；如果该费率**低于你的** `minRewardRate`（或无法报出费率），调用将**失败**，而不会以更低费率完成购买。这是避免在高费率的库存优惠售罄后，不经意间以更低费率的可变额优惠购买剩余卡片的推荐做法。

> 🚧 `minRewardRate` 仅适用于使用 `merchantSlug` 的购买。
>
> 如果你提供了 `offerId`，则会忽略 `minRewardRate`（优惠及其费率已被固定）。该下限按调用逐一评估，因此在购买多张卡时，请在每次调用中都包含它。

### 缺货错误

当某个优惠因库存原因无法履约时，变更请求将返回：

```json theme={null}
{
  "code": "GC-0009",
  "message": "This offer is currently out of stock. Please select a different amount or try again later."
}
```

在重试前，使用 `getOfferQuote` / `getMerchants` 重新报价以找到当前最佳可用优惠。

> 📘
>
> ### 当你购买的卡数超过库存时会发生什么假设某商户的最佳优惠是一个固定、按库存跟踪的优惠，只剩下 **8** 个库存，而你想要 **10** 张卡（10 次单独的 `purchaseGiftCard` 调用）：
>
> * **使用** `offerId`（固定到该固定优惠）：前 8 次调用会以库存费率成功；第 9 次和第 10 次调用会以 `GC-0009` **失败**。不会自动回退到其他优惠或费率。
> * **使用** `merchantSlug`（自动选择）：前 8 次调用会以更高费率在固定优惠上完成购买；一旦其售罄，剩余调用会自动选择**下一个最佳可用优惠**——这可能是**奖励费率更低的可变额优惠**。

> 🚧
>
> ### 使用 `minRewardRate` 保护你的费率当使用 `merchantSlug` 购买时，请将 `minRewardRate` 设为奖励费率下限。每次购买前，系统都会检查该商户在该金额与支付方式下可提供的最佳费率；如果该费率**低于**你的 `minRewardRate`（或无法报出费率），调用将**失败**，而不是以更低费率完成购买。这是避免在高费率的库存优惠售罄后，不经意间以更低费率的可变额优惠购买剩余卡片的推荐方式。
>
> 当你提供 `offerId` 时将**忽略** `minRewardRate`（费率已被固定），并且它会**按调用**进行评估——在购买多张卡时，每次调用都要包含它。

要在购买前检查库存，请参见 [Get Inventory On Stocked Offers](/get-inventory)。