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 個為這項產品指定的自訂標記清單，並透過帳單程式庫傳回應用程式。

州

訂閱方案的目前狀態。

列舉
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 的分數。系統會將計算結果四捨五入至最接近的可計費單位 (例如美元的 cents)。如果折扣價低於該地區允許的最低價格，相對折扣就會視為無效。
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 的分數。系統會將計算結果四捨五入至最接近的可計費單位 (例如美元的 cents)。如果折扣價低於 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} [帳單週期為 {billing_period}]。

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 錯誤碼：

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

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

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

 重試要求。