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