REST Resource: monetization.subscriptions.basePlans.offers

資源：SubscriptionOffer

單一臨時優惠

JSON 表示法 
{
  "packageName": string,
  "productId": string,
  "basePlanId": string,
  "offerId": string,
  "state": enum (State),
  "phases": [
    {
      object (SubscriptionOfferPhase)
    }
  ],
  "targeting": {
    object (SubscriptionOfferTargeting)
  },
  "regionalConfigs": [
    {
      object (RegionalSubscriptionOfferConfig)
    }
  ],
  "otherRegionsConfig": {
    object (OtherRegionsSubscriptionOfferConfig)
  },
  "offerTags": [
    {
      object (OfferTag)
    }
  ]
}
欄位
packageName

string

必填。不可變動。父項訂閱項目所屬應用程式的套件名稱。
productId

string

必填。不可變動。此優惠所屬的父項訂閱方案 ID。
basePlanId

string

必填。不可變動。此優惠擴充功能所屬的基本方案 ID。
offerId

string

必填。不可變動。這項訂閱方案的專屬 ID。在基本方案中不得重複。
state

enum (State)

僅供輸出。這項優惠的目前狀態。可使用「啟用」和「停用」動作變更。注意：基本方案狀態會取代此狀態，因此如果基本方案未啟用，有效優惠可能無法使用。
phases[]

object (SubscriptionOfferPhase)

必填。這項訂閱優惠的階段。至少要有一項，最多兩項。使用者一律會依指定順序收到所有階段的通知。
targeting

object (SubscriptionOfferTargeting)

使用者必須符合的條件，才能享有這項優惠。代表 Play 將評估的需求，以決定是否應傳回方案。開發人員可以自行進一步篩選這些優惠。
regionalConfigs[]

object (RegionalSubscriptionOfferConfig)

必填。這項優惠的區域專屬設定。至少須包含一個項目。
otherRegionsConfig

object (OtherRegionsSubscriptionOfferConfig)

Google Play 日後可能推出的新地區設定。
offerTags[]

object (OfferTag)

列出這項產品專屬的自訂標記，最多可達 20 個，並透過 Billing Library API 傳回應用程式。

州

訂閱方案的目前狀態。

列舉
STATE_UNSPECIFIED 預設值，不應使用。
DRAFT 延續過去做法，使用者無法享有這項訂閱優惠。
ACTIVE 這項訂閱優惠適用於新使用者和現有使用者。
INACTIVE 新使用者無法享有訂閱優惠。現有使用者仍可存取。

SubscriptionOfferPhase

訂閱方案的單一階段。

JSON 表示法 
{
  "recurrenceCount": integer,
  "duration": string,
  "regionalConfigs": [
    {
      object (RegionalSubscriptionOfferPhaseConfig)
    }
  ],
  "otherRegionsConfig": {
    object (OtherRegionsSubscriptionOfferPhaseConfig)
  }
}
欄位
recurrenceCount

integer

必填。這個階段的重複次數。如果這個優惠階段並非免費，系統會在每個週期向使用者收取這個優惠階段的價格。
duration

string

必填。這個階段單次重複的持續時間，以 ISO 8601 格式指定。
regionalConfigs[]

object (RegionalSubscriptionOfferPhaseConfig)

必填。這項商品階段的區域專屬設定。這份清單必須為訂閱方案設有區域設定的每個區域，都包含一個項目。
otherRegionsConfig

object (OtherRegionsSubscriptionOfferPhaseConfig)

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

RegionalSubscriptionOfferPhaseConfig

單一區域中訂閱方案單一階段的設定。

JSON 表示法 
{
  "regionCode": string,

  // Union field price_override can be only one of the following:
  "price": {
    object (Money)
  },
  "relativeDiscount": number,
  "absoluteDiscount": {
    object (Money)
  },
  "free": {
    object (RegionalSubscriptionOfferPhaseFreePriceOverride)
  }
  // End of list of possible types for union field price_override.
}
欄位
regionCode

string

必填。不可變動。這項設定適用的區域。
聯集欄位 price_override。這個階段的價格覆寫。必填。price_override 只能是下列其中一項：
price

object (Money)

使用者為這項優惠階段支付的絕對價格。價格不得低於該區域允許的最低價格。
relativeDiscount

number

使用者為這項優惠階段支付的費用，是按階段時間長度比例計算的基本方案價格。舉例來說，如果這個區域的基本方案價格為 $12 美元 (1 年)，則為期 3 個月的階段提供 50% 的折扣，就相當於 $1.50 美元。折扣比例必須指定為大於 0 且小於 1 的分數。計算出的價格會四捨五入至最接近的可計費單位 (例如「美分」)。如果折扣價低於該地區允許的最低價格，相對折扣就會視為無效。
absoluteDiscount

object (Money)

從按比例計算的階段基本方案價格中扣除的金額，即使用者為這項優惠階段支付的費用。舉例來說，如果這個區域的基本方案價格為 $12 美元 (1 年)，則 3 個月階段的 $1 美元絕對折扣相當於 $2 美元。最終價格不得低於該地區允許的最低價格。
free

object (RegionalSubscriptionOfferPhaseFreePriceOverride)

設為指定這項優惠可免費取得。

RegionalSubscriptionOfferPhaseFreePriceOverride

這個類型沒有任何欄位。

代表訂閱方案單一階段的免費價格覆寫設定

OtherRegionsSubscriptionOfferPhaseConfig

在單一優惠階段，為 Play 可能推出的任何新地區設定。

JSON 表示法 
{

  // Union field price_override can be only one of the following:
  "otherRegionsPrices": {
    object (OtherRegionsSubscriptionOfferPhasePrices)
  },
  "relativeDiscount": number,
  "absoluteDiscounts": {
    object (OtherRegionsSubscriptionOfferPhasePrices)
  },
  "free": {
    object (OtherRegionsSubscriptionOfferPhaseFreePriceOverride)
  }
  // End of list of possible types for union field price_override.
}
欄位
聯集欄位 price_override。這個階段的價格覆寫。必填。price_override 只能是下列其中一項：
otherRegionsPrices

object (OtherRegionsSubscriptionOfferPhasePrices)

使用者為這項優惠階段支付的絕對價格。價格不得低於 Play 在任何新地區推出的最低價格。
relativeDiscount

number

使用者為這項優惠階段支付的價格比例，以基本方案價格按階段時間長度比例計算。舉例來說，如果這個區域的基本方案價格為 $12 美元 (1 年)，則為期 3 個月的階段提供 50% 的折扣，就相當於 $1.50 美元。折扣比例必須指定為大於 0 且小於 1 的分數。計算出的價格會四捨五入至最接近的可計費單位 (例如「美分」)。如果折扣價低於 Play 可能推出的任何新地區允許的最低價格，相對折扣就會視為無效。
absoluteDiscounts

object (OtherRegionsSubscriptionOfferPhasePrices)

使用者為這項優惠階段支付的金額，是從按階段時間長度比例計算的基本方案價格中扣除的絕對金額。舉例來說，如果這個區域的基本方案價格為 $12 美元 (1 年)，則 3 個月階段的 $1 美元絕對折扣相當於 $2 美元。最終價格不得低於 Play 在任何新地區推出的最低價格。
free

object (OtherRegionsSubscriptionOfferPhaseFreePriceOverride)

設為指定這項優惠可免費取得。

OtherRegionsSubscriptionOfferPhasePrices

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

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

object (Money)

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

object (Money)

必填。Play 在任何新地點推出時使用的歐元價格。

OtherRegionsSubscriptionOfferPhaseFreePriceOverride

這個類型沒有任何欄位。

代表 Play 可能為單一方案階段推出的任何新地點，所適用的免費價格覆寫設定。

SubscriptionOfferTargeting

定義使用者必須符合的規則，才能收到這項優惠。

JSON 表示法 
{

  // Union field rule can be only one of the following:
  "acquisitionRule": {
    object (AcquisitionTargetingRule)
  },
  "upgradeRule": {
    object (UpgradeTargetingRule)
  }
  // End of list of possible types for union field rule.
}
欄位
聯集欄位 rule。如要由開發人員決定優惠資格，請留空。rule 只能是下列其中一項：
acquisitionRule

object (AcquisitionTargetingRule)

新使用者開發的優惠目標規則。
upgradeRule

object (UpgradeTargetingRule)

為升級現有方案的使用者提供優惠的指定目標規則。

AcquisitionTargetingRule

代表目標對象規則，格式為：使用者從未擁有{範圍}。

JSON 表示法 
{
  "scope": {
    object (TargetingRuleScope)
  }
}
欄位
scope

object (TargetingRuleScope)

必填。這項規則考量的訂閱項目範圍。只允許「這項訂閱項目」和「應用程式中的任何訂閱項目」。

TargetingRuleScope

定義目標規則可比對的訂閱項目範圍，根據使用者過去或目前的權益，向使用者放送目標優惠。

JSON 表示法 
{

  // Union field scope can be only one of the following:
  "thisSubscription": {
    object (TargetingRuleScopeThisSubscription)
  },
  "anySubscriptionInApp": {
    object (TargetingRuleScopeAnySubscriptionInApp)
  },
  "specificSubscriptionInApp": string
  // End of list of possible types for union field scope.
}
欄位

聯集欄位 scope。

scope 只能是下列其中一項：
thisSubscription

object (TargetingRuleScopeThisSubscription)

目前指定目標規則的範圍是定義這項優惠的訂閱項目。
anySubscriptionInApp

object (TargetingRuleScopeAnySubscriptionInApp)

目前指定目標規則的適用範圍是父項應用程式中的任何訂閱項目。
specificSubscriptionInApp

string

目前指定目標規則的範圍是具有指定訂閱 ID 的訂閱項目。必須是同一父項應用程式中的訂閱項目。

TargetingRuleScopeThisSubscription

這個類型沒有任何欄位。

代表與定義這項方案的訂閱項目相應的指定目標規則範圍。

TargetingRuleScopeAnySubscriptionInApp

這個類型沒有任何欄位。

代表父項應用程式中任何訂閱項目的相應指定目標規則範圍。

UpgradeTargetingRule

代表目標對象規則，格式為：使用者目前有 {scope} [帳單週期為 {billingPeriod}]。

JSON 表示法 
{
  "oncePerUser": boolean,
  "scope": {
    object (TargetingRuleScope)
  },
  "billingPeriodDuration": string
}
欄位
oncePerUser

boolean

每位使用者只能兌換這項優惠一次。如果設為 true，使用者只要訂閱過這項優惠，就永遠無法再次享有這項優惠。
scope

object (TargetingRuleScope)

必填。這項規則考量的訂閱項目範圍。只允許「這項訂閱項目」和「應用程式中的特定訂閱項目」。
billingPeriodDuration

string

以 ISO 8601 格式指定的特定帳單週期長度，使用者必須目前訂閱此方案，才能符合這項規則的資格。如未指定，訂閱任何帳單週期的使用者都符合資格。

RegionalSubscriptionOfferConfig

單一區域的訂閱方案設定。

JSON 表示法 
{
  "regionCode": string,
  "newSubscriberAvailability": boolean
}
欄位
regionCode

string

必填。不可變動。這項設定適用的區域代碼，如 ISO 3166-2 所定義，例如「US」。
newSubscriberAvailability

boolean

指定區域的訂閱方案是否適用於新訂閱者。如果將這個值設為 false，現有訂閱者不會遭到取消訂閱。如未指定，則預設為 false。

OtherRegionsSubscriptionOfferConfig

Play 可能會在訂閱方案中指定的新地點推出，因此需要進行設定。

JSON 表示法 
{
  "otherRegionsNewSubscriberAvailability": boolean
}
欄位
otherRegionsNewSubscriberAvailability

boolean

是否要在 Google Play 日後可能推出的新地區提供訂閱優惠。如未指定，則預設為 false。

方法

activate

 啟用訂閱優惠。

batchGet

 讀取一或多項訂閱方案。

batchUpdate

 更新整批訂閱方案。

batchUpdateStates

 更新整批訂閱方案狀態。

create

 建立新的訂閱方案。

deactivate

 停用訂閱優惠。

delete

 刪除訂閱方案。

get

 讀取單一優惠

list

 列出指定訂閱方案的所有優惠。

patch

 更新現有的訂閱方案。

錯誤代碼

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

錯誤代碼 原因 說明 解析度