REST Resource: monetization.subscriptions

資源：Subscription

應用程式的單一訂閱方案。

JSON 表示法 
{
  "packageName": string,
  "productId": string,
  "basePlans": [
    {
      object (BasePlan)
    }
  ],
  "listings": [
    {
      object (SubscriptionListing)
    }
  ],
  "archived": boolean,
  "taxAndComplianceSettings": {
    object (SubscriptionTaxAndComplianceSettings)
  },
  "restrictedPaymentCountries": {
    object (RestrictedPaymentCountries)
  }
}
欄位
packageName

string

不可變更。父項應用程式的套件名稱。
productId

string

不可變更。產品的專屬產品 ID。在父項應用程式中不得重複。產品 ID 必須由小寫字母 (a-z)、數字 (0-9)、底線 (_) 和半形句點 (.) 組成，且開頭必須是小寫字母或數字，長度介於 1 到 40 個半形字元之間 (含首尾)。
basePlans[]

object (BasePlan)

這項訂閱方案的基本方案組合。如果沒有其他優惠適用，則代表訂閱價格和訂閱時間。
listings[]

object (SubscriptionListing)

必要欄位。這項訂閱項目的本地化商店資訊清單。至少須包含父項應用程式預設語言的項目。
archived
(deprecated)

boolean

僅供輸出。已淘汰：系統不支援封存訂閱項目。
taxAndComplianceSettings

object (SubscriptionTaxAndComplianceSettings)

稅金和法律遵循相關詳細資料。
restrictedPaymentCountries

object (RestrictedPaymentCountries)

(選用步驟) 在這些國家/地區，購買此訂閱項目時只能使用當地登錄的付款方式。如果留空，系統不會套用任何付款地區限制。

BasePlan

訂閱項目的單一基本方案。

JSON 表示法 
{
  "basePlanId": string,
  "state": enum (State),
  "regionalConfigs": [
    {
      object (RegionalBasePlanConfig)
    }
  ],
  "offerTags": [
    {
      object (OfferTag)
    }
  ],
  "otherRegionsConfig": {
    object (OtherRegionsBasePlanConfig)
  },

  // Union field base_plan_type can be only one of the following:
  "autoRenewingBasePlanType": {
    object (AutoRenewingBasePlanType)
  },
  "prepaidBasePlanType": {
    object (PrepaidBasePlanType)
  },
  "installmentsBasePlanType": {
    object (InstallmentsBasePlanType)
  }
  // End of list of possible types for union field base_plan_type.
}
欄位
basePlanId

string

必要欄位。不可變更。這個基本方案的專屬 ID。訂閱項目中的名稱不得重複，且必須符合 RFC-1034。也就是說，這個 ID 只能包含小寫字母 (a-z)、數字 (0-9) 和連字號 (-)，且不得超過 63 個字元。
state

enum (State)

僅供輸出。基本方案的狀態，即是否有效。您可以啟用或刪除草稿和已停用的基本方案。你可以停用有效基本方案，你可以取消未啟用的基本方案。更新資源後，這個欄位無法變更。請改用專屬端點。
regionalConfigs[]

object (RegionalBasePlanConfig)

這個基礎方案的特定地區資訊。
offerTags[]

object (OfferTag)

最多 20 個為這個基本方案指定的自訂標記清單，並透過帳款服務程式庫回傳至應用程式。基本方案的訂閱優惠也會在帳單資料庫中收到這些優惠標記。
otherRegionsConfig

object (OtherRegionsBasePlanConfig)

Google Play 日後可能推出的新地區價格資訊。如果省略，BasePlan 將不會自動在 Play 未來可能推出的任何新地點提供。
聯集欄位 base_plan_type。這個基本方案的類型。必須設定其中一個。建立基本方案後，就無法變更基本方案類型。base_plan_type 只能是下列其中一項：
autoRenewingBasePlanType

object (AutoRenewingBasePlanType)

設定基本方案自動續訂的固定時間間隔。
prepaidBasePlanType

object (PrepaidBasePlanType)

設定基本方案在帳單週期結束時不自動續訂。
installmentsBasePlanType

object (InstallmentsBasePlanType)

使用者承諾支付特定次數的款項，適用於分期付款基本方案。

州

基本方案的目前狀態。

列舉
STATE_UNSPECIFIED 未指定狀態。
DRAFT 基本方案目前處於草稿狀態，尚未啟用。此時可以放心刪除。
ACTIVE 基本方案有效，新訂閱者可使用。
INACTIVE 基本方案已停用，僅適用於現有訂閱者。

AutoRenewingBasePlanType

代表基本方案會在訂閱週期結束時自動續訂。

JSON 表示法 
{
  "billingPeriodDuration": string,
  "gracePeriodDuration": string,
  "accountHoldDuration": string,
  "resubscribeState": enum (ResubscribeState),
  "prorationMode": enum (SubscriptionProrationMode),
  "legacyCompatible": boolean,
  "legacyCompatibleSubscriptionOfferId": string
}
欄位
billingPeriodDuration

string

必要欄位。不可變更。以 ISO 8601 格式指定的訂閱期。如需可接受的帳單週期清單，請參閱說明中心。建立基本方案後，就無法變更期限。
gracePeriodDuration

string

訂閱項目的寬限期，以 ISO 8601 格式指定。可接受的值必須以天為單位，且介於 P0D 和 30D 之間，或基本方案帳單週期 (以較小者為準)。

如未指定，系統會根據帳單週期使用預設值。

gracePeriodDuration 和 accountHoldDuration 的總和必須介於 P30D 和 P60D 天之間 (含首尾兩天)。
accountHoldDuration

string

(選用步驟) 以 ISO 8601 格式指定的訂閱帳戶保留期。可接受的值必須以天為單位，且介於 P0D 和 P60D 之間。

如未指定，則預設值為 P30D。

gracePeriodDuration 和 accountHoldDuration 的總和必須介於 P30D 和 P60D 天之間 (含首尾兩天)。
resubscribeState

enum (ResubscribeState)

使用者是否應能在 Google Play 介面重新訂閱這個基本方案。如未指定，預設為 RESUBSCRIBE_STATE_ACTIVE。
prorationMode

enum (SubscriptionProrationMode)

基本方案的按比例計算模式會決定使用者從其他基本方案改用此方案時會發生的情況。如未指定，預設值為 CHARGE_ON_NEXT_BILLING_DATE。
legacyCompatible

boolean

續訂的基本方案是否回溯相容。

回溯相容基本方案是由 Google Play Billing Library 已淘汰的 querySkuDetailsAsync() 方法傳回。

每個訂閱項目只能將一個續訂型基本方案標示為與舊版相容。
legacyCompatibleSubscriptionOfferId

string

與舊版相容的訂閱方案 ID。

回溯相容訂閱方案是由 Google Play Billing Library 已淘汰的 querySkuDetailsAsync() 方法傳回。

針對特定續訂基本方案，只能將一項訂閱方案標示為與舊版相容。

如要將訂閱方案設為與舊版不相容，請將這個欄位設為空字串。

ResubscribeState

基本方案的重新訂閱狀態。

列舉
RESUBSCRIBE_STATE_UNSPECIFIED 未指定狀態。
RESUBSCRIBE_STATE_ACTIVE 重新訂閱功能已啟用。
RESUBSCRIBE_STATE_INACTIVE 無法重新訂閱。

SubscriptionProrationMode

用於續訂基本方案的按比例計算模式。

列舉
SUBSCRIPTION_PRORATION_MODE_UNSPECIFIED 未指定模式。
SUBSCRIPTION_PRORATION_MODE_CHARGE_ON_NEXT_BILLING_DATE 系統將在使用者目前的帳單週期結束時，向他們收取新基本方案費用。
SUBSCRIPTION_PRORATION_MODE_CHARGE_FULL_PRICE_IMMEDIATELY 系統會立即向使用者收取新基本方案的全額費用。系統會將現有訂閱方案的剩餘時間，併入新的帳單方案。

PrepaidBasePlanType

代表基本方案到期後不會自動續訂，使用者必須手動續訂。

JSON 表示法 
{
  "billingPeriodDuration": string,
  "timeExtension": enum (TimeExtension)
}
欄位
billingPeriodDuration

string

必要欄位。不可變更。以 ISO 8601 格式指定的訂閱期。如需可接受的帳單週期清單，請參閱說明中心。建立基本方案後，就無法變更期限。
timeExtension

enum (TimeExtension)

使用者是否應能在 Google Play 介面延長這個預付基本方案的效期。如未指定，預設為 TIME_EXTENSION_ACTIVE。

TimeExtension

延長基本方案時間。

列舉
TIME_EXTENSION_UNSPECIFIED 未指定狀態。
TIME_EXTENSION_ACTIVE 時間延長功能已啟用。使用者可以儲值或延長預付方案效期。
TIME_EXTENSION_INACTIVE 時間延長功能已停用。使用者無法加值或延長預付方案效期。

InstallmentsBasePlanType

代表分期付款基本方案，使用者承諾支付指定次數的款項。

JSON 表示法 
{
  "billingPeriodDuration": string,
  "committedPaymentsCount": integer,
  "renewalType": enum (RenewalType),
  "gracePeriodDuration": string,
  "accountHoldDuration": string,
  "resubscribeState": enum (ResubscribeState),
  "prorationMode": enum (SubscriptionProrationMode)
}
欄位
billingPeriodDuration

string

必要欄位。不可變更。以 ISO 8601 格式指定的訂閱期。如需可接受的帳單週期清單，請參閱說明中心。建立基本方案後，就無法變更期限。
committedPaymentsCount

integer

必要欄位。不可變更。使用者承諾付款的次數。建立基本方案後即無法變更。
renewalType

enum (RenewalType)

必要欄位。不可變更。分期付款基本方案續訂類型。決定初始承諾期結束時的行為。建立基本方案後，續訂類型就無法變更。
gracePeriodDuration

string

訂閱項目的寬限期，以 ISO 8601 格式指定。可接受的值必須以天為單位，且介於 P0D 和 30D 之間，或基本方案帳單週期 (以較小者為準)。

如未指定，系統會根據帳單週期使用預設值。

gracePeriodDuration 和 accountHoldDuration 的總和必須介於 P30D 和 P60D 天之間 (含首尾兩天)。
accountHoldDuration

string

(選用步驟) 以 ISO 8601 格式指定的訂閱帳戶保留期。可接受的值必須以天為單位，且介於 P0D 和 P60D 之間。

如未指定，則預設值為 P30D。

gracePeriodDuration 和 accountHoldDuration 的總和必須介於 P30D 和 P60D 天之間 (含首尾兩天)。
resubscribeState

enum (ResubscribeState)

使用者是否應能在 Google Play 介面重新訂閱這個基本方案。如未指定，預設為 RESUBSCRIBE_STATE_ACTIVE。
prorationMode

enum (SubscriptionProrationMode)

基本方案的按比例計算模式會決定使用者從其他基本方案改用此方案時會發生的情況。如未指定，預設值為 CHARGE_ON_NEXT_BILLING_DATE。

RenewalType

分期付款基本方案續訂類型。決定初始承諾期結束時的行為。建立基本方案後，續訂類型就無法變更。

列舉
RENEWAL_TYPE_UNSPECIFIED 未指定狀態。
RENEWAL_TYPE_RENEWS_WITHOUT_COMMITMENT 系統會定期續訂，無須承諾，續訂週期與帳單週期相同。
RENEWAL_TYPE_RENEWS_WITH_COMMITMENT 續訂時，承諾時間與首次訂閱時間相同。

RegionalBasePlanConfig

特定區域的基本方案設定。

JSON 表示法 
{
  "regionCode": string,
  "newSubscriberAvailability": boolean,
  "price": {
    object (Money)
  }
}
欄位
regionCode

string

必要欄位。這項設定適用的區域代碼，如 ISO 3166-2 所定義，例如「US」。
newSubscriberAvailability

boolean

指定區域的基本方案是否適用於新訂閱者。如果將這個值設為 false，現有訂閱者就不會取消訂閱。如未指定，這項屬性預設為 false。
price

object (Money)

指定區域的基本方案價格。如果基本方案開放新訂閱者選購，就必須設定這項屬性。必須以與指定區域連結的貨幣設定。

OtherRegionsBasePlanConfig

Google Play 可能推出的任何新地點的價格資訊。

JSON 表示法 
{
  "usdPrice": {
    object (Money)
  },
  "eurPrice": {
    object (Money)
  },
  "newSubscriberAvailability": boolean
}
欄位
usdPrice

object (Money)

必要欄位。Play 在任何新地點推出時使用的美元價格。
eurPrice

object (Money)

必要欄位。在 Play 可能推出的任何新地點使用的歐元價格。
newSubscriberAvailability

boolean

基本方案是否適用於 Play 可能推出的任何新地區。如未指定，這項屬性預設為 false。

SubscriptionListing

向消費者顯示的訂閱項目中繼資料。

JSON 表示法 
{
  "languageCode": string,
  "title": string,
  "benefits": [
    string
  ],
  "description": string
}
欄位
languageCode

string

必要欄位。此商店資訊的語言，如 BCP-47 所定義，例如「en-US」。
title

string

必要欄位。這個訂閱方案的名稱，以這個資訊的語言顯示。純文字。
benefits[]

string

在 Play 商店等平台和還原流程中，以這個商店資訊的語言向使用者顯示的福利清單。純文字。最多四項福利的排序清單。
description

string

以這個語言列出的訂閱方案說明。長度上限為 80 個半形字元。純文字。

方法

archive
(deprecated)

 已淘汰：系統不支援封存訂閱項目。

batchGet

 讀取一或多個訂閱項目。

batchUpdate

 更新多個訂閱項目。

create

 建立新的訂閱項目。

delete

 刪除訂閱項目。

get

 讀取單一訂閱項目。

list

 列出指定應用程式的所有訂閱項目。

patch

 更新現有訂閱項目。

錯誤代碼

這項資源的作業會傳回下列 HTTP 錯誤碼：

錯誤代碼 原因 解析度
5xx Google Play 伺服器發生一般錯誤。 重試要求。

如果問題持續發生，請與 Google Play 帳戶管理員聯絡，或提交支援要求。 建議查看 Play 狀態資訊主頁，瞭解是否有已知服務中斷情形。
409 並行更新錯誤。

嘗試更新正在更新的物件。舉例來說，購買交易同時透過呼叫 Play 帳款服務程式庫的 acknowledgePurchase() 方法和 Play Developer API 的 purchases.products.acknowledge 進行確認。

 重試要求。