REST Resource: monetization.subscriptions

資源:訂閱

應用程式的單一訂閱項目。

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)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "autoRenewingBasePlanType": {
    object (AutoRenewingBasePlanType)
  },
  "prepaidBasePlanType": {
    object (PrepaidBasePlanType)
  },
  "installmentsBasePlanType": {
    object (InstallmentsBasePlanType)
  }
  // End of mutually exclusive fields.
  "transitionTargetConfig": {
    object (TransitionTargetConfig)
  }
}
欄位
basePlanId

string

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

state

enum (State)

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

regionalConfigs[]

object (RegionalBasePlanConfig)

這項基本方案的區域專屬資訊。

offerTags[]

object (OfferTag)

列出這項基本方案專屬的自訂標記,最多可達 20 個,並透過 Billing Library API 傳回應用程式。這個基本方案的訂閱優惠也會在 Billing Library 中收到這些優惠標記。

otherRegionsConfig

object (OtherRegionsBasePlanConfig)

Google Play 日後可能推出的任何新地區定價資訊。如果省略,基本方案就不會自動在 Play 日後可能推出的新地區提供。

這個基本方案的類型。必須設定一個選項。基本方案建立後,類型即無法變更。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位:
autoRenewingBasePlanType

object (AutoRenewingBasePlanType)

設定基本方案定期自動續訂的時間。

prepaidBasePlanType

object (PrepaidBasePlanType)

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

installmentsBasePlanType

object (InstallmentsBasePlanType)

為分期付款基本方案設定,使用者承諾支付指定次數的款項。

互斥欄位結束。
transitionTargetConfig

object (TransitionTargetConfig)

如果這個基本方案有轉換計畫,則會顯示轉換目標基本方案資訊。

州

基本方案的目前狀態。

列舉
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 之間。

如果欄位留空,代表建議的帳戶保留期,計算方式為 60 天減去寬限期。

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

續訂 Base 方案時使用的比例計費模式。

列舉
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 之間。

如果欄位留空,代表建議的帳戶保留期,計算方式為 60 天減去寬限期。

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-1 alpha-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

是否要在 Google Play 日後可能支援的新地區,向新訂閱者提供基本方案。如未指定,則預設為 false。

TransitionTargetConfig

轉換目標基本方案的設定。

JSON 表示法
{
  "productId": string,
  "basePlanId": string
}
欄位
productId

string

必填。這個轉換目標基本方案所屬的父項訂閱項目 ID。

basePlanId

string

必填。轉換目標基本方案的 ID。

SubscriptionListing

訂閱項目的中繼資料,消費者可查看。

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

string

必填。這個商店資訊的語言 (由 BCP-47 定義),例如「en-US」。

title

string

必填。這個訂閱項目的名稱 (以這則資訊的語言顯示)。純文字。

benefits[]

string

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

description

string

以這項產品資訊的語言,提供這個訂閱項目的說明。長度上限為 200 個半形字元。純文字。

方法

archive
(deprecated)

已淘汰:不支援封存訂閱項目。

batchGet

讀取一或多個訂閱項目。

batchUpdate

更新整批訂閱項目。

create

建立新的訂閱項目。

delete

刪除訂閱項目。

get

讀取單一訂閱項目。

list

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

patch

更新現有訂閱項目。

錯誤代碼

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

錯誤代碼 原因 說明 解析度