> ## 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` 字段，且一次调用绝不会在多个优惠或费率之间拆分。若需购买多张卡，请多次发送该 mutation——每张卡各一次，并使用其各自唯一的 `idempotencyKey`。

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

### 购买流程一览

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

### `offerId` — 固定到特定优惠与费率

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

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

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

### 固定面额 vs. 浮动面额与库存

* **固定面额优惠**会按面额逐一跟踪库存。某一面额一旦售罄，将不可再被选择，任何通过 `offerId` 固定到该面额的后续调用都会返回缺货错误。
* **浮动面额优惠**并不以同样方式受库存限制。它通常持续可用，并在固定/有库存跟踪的优惠售罄后作为回退方案。浮动面额优惠通常会有一个**不同（往往更低）的奖励费率**，取代已售罄的固定面额优惠。

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

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

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

> 🚧 `minRewardRate` 仅适用于通过 `merchantSlug` 的购买。
>
> 若你提供了 `offerId`，则会忽略 `minRewardRate`（优惠及其费率已固定）。该下限会按调用逐次评估，因此在批量购买时请在每次调用中都包含该参数。

### 缺货错误

当某个优惠因库存原因不再可履约时，mutation 会返回：

```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)。