Skip to main content
單次 purchaseGiftCard 呼叫會購買恰好一張禮品卡，對應一個優惠與一個回饋率。沒有 quantity 欄位，且單次呼叫不會被拆分到多個優惠或回饋率。若要購買多張卡，請多次送出 mutation——每張卡呼叫一次，且每次使用自己的 idempotencyKey。 每次呼叫如何選擇優惠與回饋率，取決於你是傳入 offerId 還是 merchantSlug。

​
購買流程一覽

​
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 會回傳：
在重試前，請使用 getOfferQuote / getMerchants 重新取得報價，以找到當前最佳可用優惠。
📘

​
當你購買的張數超過庫存時會發生什麼事 假設某商家的最佳優惠是固定、可追蹤庫存的優惠，只剩下 8 張，而你想要 10 張卡（10 次獨立的 purchaseGiftCard 呼叫）：

  • 使用 offerId（鎖定固定優惠）：前 8 次呼叫會以庫存回饋率成功；第 9 與第 10 次呼叫會因 GC-0009 失敗。不會自動改用其他優惠或回饋率。
  • 使用 merchantSlug（自動選擇）：前 8 次呼叫會以較高回饋率的固定優惠購買；一旦售罄，剩餘呼叫會自動選擇次佳可用優惠——可能是回饋率較低的可變額度優惠。
🚧

​
使用 minRewardRate 保護你的回饋率 當以 merchantSlug 購買時，設定 minRewardRate 作為回饋率下限。系統會在每次購買前檢查該商家、金額與付款方式的最佳可用回饋率；若該回饋率低於你的 minRewardRate（或無法報價），該次呼叫將失敗，而不會以較低回饋率購買。這是避免在較高回饋率的有庫存固定優惠售罄後，剩餘張數被不小心購於較低回饋率可變額度優惠的建議作法。

當你提供 offerId 時會忽略 minRewardRate（回饋率已固定），且該下限會逐次呼叫評估——在購買多張卡時，請於每次呼叫都包含它。
若要在購買前檢查庫存，請參見 取得有庫存優惠的存量。