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