當 Google Play 的購買被退款或被 chargeback 時，Voided Purchases API 就是你得知此事的方式

Google Play 上的退款不會來敲你的門。錢款移動了，客戶還開著 App，除非你去找，否則你這邊什麼都不會改變。Voided Purchases API 就是你去找的地方。它交給你一份已取消、退款或 chargeback 的訂單清單，讓你可以撤銷客戶不再付費之物的存取權。把一個排程工作指向它，讀取清單，切斷權限。這就是整個循環。

有一個陷阱會絆倒大多數團隊，而且它不在程式碼裡。只有被 revoke 的訂單才會在這裡出現。如果你在 Play Console 退款一筆購買卻沒有勾選 revoke 選項，那筆訂單永遠不會到達這個 API，而你的工作會乾淨地執行，同時一個已退款的客戶保留了你賣給他的一切。這篇文章逐一欄位走過這個 API、界定它的數字，以及當你略過它時錢從哪裡漏出去。

Voided Purchases API 實際上回傳什麼

這個 API 回答一個問題：這個 App 的哪些訂單最近被作廢了。作廢涵蓋三種都以客戶拿回錢款告終的結果。取消、退款或 chargeback。它適用於一次性的 App 內產品和訂閱，而你用單一參數選擇範圍。把 type 設為 0，你就只會得到被作廢的 App 內產品購買，這是預設值。把它設為 1，你就會同時得到被作廢的 App 內購買和被作廢的訂閱購買。

清單中的每一筆項目都是一個被作廢的購買物件。欄位不多，而且每一個都重要。

被作廢購買上的欄位

在採取行動之前先讀 voidedReason

voidedReason 是把原始清單轉成決策的欄位。買家後悔的退款和銀行的 chargeback 都落在同一份清單裡，但它們不是同一種事件，而八月的定價讓其中一種變得昂貴。以下是完整的一組。

30 天的時間窗是清空你清單的陷阱

Voided Purchases API 只能顯示過去 30 天內被作廢的購買。startTime 參數預設為目前時間減 30 天，而且不能設得比那更早。endTime 預設為現在。所以這個端點是一個滾動的一個月時間窗，而不是一個封存檔案。

後果很直接。如果你的輪詢工作壞了而五週內沒有人注意到，第一週的作廢就已經因逾期而離開了 API。沒有任何呼叫能把它們帶回來。你不會撤銷那些訂單，而且除非你用其他方式擷取過它們，否則你甚至不會知道它們曾經存在。這個 API 是一張安全網，上面有一個跟你最糟糕的停機一樣大的洞。

revoke 選項決定一筆訂單是否會出現

這是團隊回報 API 壞掉的最常見原因。只有被 revoke 的訂單才會被回傳。使用者發起的退款、取消、chargeback 和 Google 發起的退款總是會被 revoke，所以它們總是會出現。開發者發起的退款則不同。當你自己退款一筆訂單，透過 Play Console 或 Orders API 時，你選擇是否也要 revoke 它。退款而不 revoke，那筆訂單就與客戶結清了，但永遠不會浮現在 Voided Purchases API 裡。

隨之而來的規則很簡單。如果你的意圖是收回存取權，就在開啟 revoke 選項的情況下退款。否則你已經退了錢卻讓門開著，而你的撤銷工作，無論寫得多好，都沒有東西可以處理。

如何在不觸及配額的情況下輪詢它

這個端點有速率限制，而限制低到一個天真的迴圈就會撞上它們。你每天有 6,000 次查詢，以太平洋時間計算，任何 30 秒期間內不超過 30 次查詢。這個預算對於視窗式輪詢綽綽有餘，卻對一筆訂單一次請求的設計充滿敵意。

查詢視窗與 continuation token

maxResults 預設為 1,000，這也是上限。當一個視窗容納超過一頁的作廢時，回應會帶著一個含有 nextPageToken 的 tokenPagination 物件。在下一次呼叫時把那個 token 傳回去，以走過各頁。設定 startTime 和 endTime 來界定你在意的視窗，翻頁直到 token 用完，然後推進視窗。這個模式讓你同時待在 30 秒的爆量限制和每日上限之內。

Real-time developer notifications 填補了空隙

每天輪詢仍會留下最多一天的盲區，而 30 天的時間窗會懲罰長間隔。Real-time developer notifications 移除了延遲。Google 會在購買被作廢的那一刻，把一個 VoidedPurchaseNotification 發佈到你擁有的 Cloud Pub/Sub topic，而你的後端會在幾秒內消費它。這則訊息很小。

這在金錢上讓你付出什麼代價

這個 API 是水電管線，但接上它的理由是一張帳單。那份清單裡的每一筆作廢都對應到一個真實的數字，而其中兩個正變得更昂貴。

從 2026 年 8 月 3 日起 chargeback 的帳單落到你身上

從 2026 年 8 月 3 日起，Google 把 chargeback 的成本轉嫁到開發者身上。你失去購買價金，還要在上面付銀行的 chargeback 手續費。voidedReason 為 7 不再只是一筆流失的銷售，它是一個附帶手續費的支出項目。你無法逆轉一筆 chargeback，它與銀行是最終定案，但你可以在它之後止血。快速抓到作廢讓你可以撤銷權限，而且對於你仍在交付的任何東西，停止在一個先退款又被撤銷付款的客戶身上花錢。

你持續付費去服務一個已退款的客戶

作廢一出現，購買價金就在那一刻消失了。你仍能控制的是持續交付的成本。一個已退款的權限每多活一個小時，你就持續為客戶不再資助的東西付費：運算、模型 API 呼叫、儲存，以及任何綁在他使用量上的創作者或夥伴分潤。一套由這個 API 驅動的撤銷系統，就是你關掉那個計量表的方式。略過它，你就是在為商店已經補償過的人資助這個產品。

Friendly fraud 是一個值得追蹤趨勢的模式

voidedReason 為 5 或 6 不是一次性的事件。Fraud 和 friendly fraud 會按帳號、按裝置，有時按促銷活動群聚。API 在每一筆作廢上給你 voidedSource 和 voidedReason，這足以按帳號追蹤濫用的趨勢，而不是把每一次撤銷付款當成一項孤立的成本。一個做了兩次 chargeback 的客戶，正告訴你第一次退款沒有告訴你的事。

用 RefundHalt 的方式把它接起來

一旦你握住所有的零件，這個模型就很小。即時聆聽 VoidedPurchaseNotification，好讓任何東西都不必等上整整一天。呼叫 Voided Purchases API 作為事實的來源，以 orderId 為鍵，好讓訂閱續訂永遠不會被搞混。讀取 voidedSource 和 voidedReason，好讓 chargeback 的處理不同於後悔退款。按一個緊到 30 天時間窗永遠不會咬到你的排程輪詢，並在你的意圖是切斷存取權時，一律在開啟 revoke 選項的情況下退款。

這就是 RefundHalt 為你執行的部分。它消費即時通知，把每一筆作廢與 API 對帳，撤銷確切的那筆訂單而不是整個產品，並把銀行 chargeback 與一筆普通退款分開，好讓昂貴的那些被標記出來，而不是被埋沒。你在幾秒內就取得被撤銷的存取權，以及一份誰作廢了什麼、為什麼的紀錄，而不必自己架起一條 Pub/Sub 管線和一個輪詢工作。