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)

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)

Play 可能推出的任何新地區定價資訊。

RegionalSubscriptionOfferPhaseConfig

單一區域中訂閱優惠單一階段的設定。

JSON 表示法 
{
  "regionCode": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "price": {
    object (Money)
  },
  "relativeDiscount": number,
  "absoluteDiscount": {
    object (Money)
  },
  "free": {
    object (RegionalSubscriptionOfferPhaseFreePriceOverride)
  }
  // End of mutually exclusive fields.
}
欄位
regionCode

string

必填。不可變動。這項設定適用的區域。
這個階段的價格覆寫。必填。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位：
price

object (Money)

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

number

從基本方案價格中扣除的折扣百分比，按階段期間比例計算，指定為大於 0 且小於 1 的分數。舉例來說，0.8 代表 80% 折扣，也就是說，如果按比例計算的基本方案價格為 $100 美元，優惠價格就會是 $20 美元。計算出的價格會四捨五入至最接近的可計費單位 (例如「美分」)。如果折扣價低於該地區允許的最低價格，相對折扣就會視為無效。
absoluteDiscount

object (Money)

從基本方案價格中扣除的絕對金額，按階段時間長度比例計算。舉例來說，如果這個區域的基本方案價格為 $12 美元，期限為 1 年，則 3 個月階段的 $1 美元絕對折扣就相當於 $2 美元。折扣後的價格不得低於該地區允許的最低價格。
free

object (RegionalSubscriptionOfferPhaseFreePriceOverride)

設定這項屬性，即可指定這項優惠可免費取得。
互斥欄位結束。

RegionalSubscriptionOfferPhaseFreePriceOverride

這個類型沒有任何欄位。

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

OtherRegionsSubscriptionOfferPhaseConfig

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

JSON 表示法 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "otherRegionsPrices": {
    object (OtherRegionsSubscriptionOfferPhasePrices)
  },
  "relativeDiscount": number,
  "absoluteDiscounts": {
    object (OtherRegionsSubscriptionOfferPhasePrices)
  },
  "free": {
    object (OtherRegionsSubscriptionOfferPhaseFreePriceOverride)
  }
  // End of mutually exclusive fields.
}
欄位
這個階段的價格覆寫。必填。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位：
otherRegionsPrices

object (OtherRegionsSubscriptionOfferPhasePrices)

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

number

從基本方案價格中扣除的折扣百分比，按階段期間比例計算，指定為大於 0 且小於 1 的分數。舉例來說，0.8 代表 80% 折扣，也就是說，如果按比例計算的基本方案價格為 $100 美元，優惠價格就會是 $20 美元。計算出的價格會四捨五入至最接近的可計費單位 (例如「美分」)。如果折扣價低於 Play 可能推出的任何新地區允許的最低價格，相對折扣就會視為無效。
absoluteDiscounts

object (OtherRegionsSubscriptionOfferPhasePrices)

從基本方案價格中扣除的絕對金額，按階段時間長度比例計算。舉例來說，如果這個區域的基本方案價格為 $12 美元，期限為 1 年，則 3 個月階段的 $1 美元絕對折扣就相當於 $2 美元。計算出的價格不得低於 Play 可能推出的任何新地區允許的最低價格。
free

object (OtherRegionsSubscriptionOfferPhaseFreePriceOverride)

設定這項屬性，即可指定這項優惠可免費取得。
互斥欄位結束。

OtherRegionsSubscriptionOfferPhasePrices

Play 可能推出的任何新地區定價資訊。

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

object (Money)

必填。Play 可能推出的任何新地區，皆以美元計價。
eurPrice

object (Money)

必填。Play 可能推出服務的新地區，將以歐元計價。

OtherRegionsSubscriptionOfferPhaseFreePriceOverride

這個類型沒有任何欄位。

代表 Play 可能為單一優惠階段推出的任何新地區，所採用的免費價格覆寫設定。

SubscriptionOfferTargeting

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

JSON 表示法 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "acquisitionRule": {
    object (AcquisitionTargetingRule)
  },
  "upgradeRule": {
    object (UpgradeTargetingRule)
  }
  // End of mutually exclusive fields.
}
欄位
如要由開發人員決定優惠資格，請留空。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位：
acquisitionRule

object (AcquisitionTargetingRule)

獲取新客的優惠指定規則。
upgradeRule

object (UpgradeTargetingRule)

升級使用者現有方案的優惠指定規則。
互斥欄位結束。

AcquisitionTargetingRule

代表以下形式的指定規則：使用者從未訂閱過 {scope}。

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

object (TargetingRuleScope)

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

TargetingRuleScope

定義指定規則可比對的訂閱項目範圍，根據使用者過去或目前的授權，向他們提供優惠。

JSON 表示法 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "thisSubscription": {
    object (TargetingRuleScopeThisSubscription)
  },
  "anySubscriptionInApp": {
    object (TargetingRuleScopeAnySubscriptionInApp)
  },
  "specificSubscriptionInApp": string
  // End of mutually exclusive fields.
}
欄位
以下是互斥欄位清單。回應中最多會設定下列其中一個欄位：
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 錯誤代碼：

錯誤代碼 原因 說明 解析度