API 版本管理
公開 API 採用日期版本，與 Shopify 相同的做法，因此你所開發依據的版本不會在腳下悄悄改變。日期版本是不相容變更的粗略界線；在同一個版本之內，schema 仍會以只增不減的方式持續演進。
版本名稱
版本名稱為 YYYY-MM，其中月份為季度起始月：2026-01、2026-04、2026-07、2026-10。只有出現不相容變更時才會切出新的日期版本——沒有不相容變更的季度會被略過，因此版本相對少見。
此外還有一個 unstable 版本，跟隨最新的開發進度，可在穩定發行前先行預覽變更。請勿在其上建構正式環境的整合。
選擇版本
有兩種方式，依優先順序排列：
- URL 路徑（建議）： 把版本寫進端點——
…/backend/<subdomain>/api/2026-07/graphql。這樣既明確、對快取友善，也方便直接複製貼上。 - 要求標頭： 對不含版本的
…/backend/<subdomain>/graphql端點送出X-Api-Version: 2026-07。
若省略版本——或指定了不存在、已過終止支援日期的版本——該要求會由仍受支援的最舊版本處理，而不是最新版本。你絕不會被悄悄升級到某個不相容的變更上。凡是打算長期維護的整合，請明確釘選版本。
每個回應都會透過 X-Api-Version 標頭指出處理它的版本，因此你隨時知道是哪一份契約作出回應；若你原本仰賴預設行為，也能藉此察覺落差。
支援期間
每個穩定版本至少支援 12 個月，並與下一個版本至少重疊 9 個月。實務上任何時候都有兩到三個版本在線上，為移轉留下寬裕的時間。版本的終止支援日期，會在其發行當天公布。
什麼算是不相容變更
在同一個版本之內，我們可能做出只增不減的變更，你的用戶端必須能夠容忍：
- 新增型別、查詢或變更（mutation）；
- 為既有欄位新增選用引數；
- 為物件型別新增欄位；
- 為列舉新增值（因此切勿假設列舉是封閉的）。
新的日期版本只保留給真正不相容的變更：移除或重新命名欄位或型別、收緊可為 null 的條件，或改變某個引數或預設值的意義。這些變更絕不會發生在既有版本內部——你所釘選的版本會維持其行為，直到終止支援日期為止。
淘汰
淘汰會以兩種方式通知，讓你在任何東西失效之前就先得知：
- 在 schema 中。 即將淘汰的欄位會標記
@deprecated，並附上指明替代方案的原因。內省與 GraphQL Playground 會自動把這些資訊呈現給每個用戶端。 - 在回應中。 當某個要求確實解析了已淘汰的欄位時，回應會帶上
X-Api-Deprecated-Reason標頭（以及對應的extensions.deprecations項目），指出它觸及的具體淘汰項目——如此一來，淘汰會在你遇上的當下就出現在紀錄中，不必特地去查。
已淘汰的欄位會保留一段已公布的最短期間，之後才會在後續的日期版本中移除。