REST Resource: monetization.onetimeproducts.purchaseOptions.offers

資源：OneTimeProductOffer

單次產品的單一優惠。

JSON 表示法 
{
  "packageName": string,
  "productId": string,
  "purchaseOptionId": string,
  "offerId": string,
  "state": enum (State),
  "regionalPricingAndAvailabilityConfigs": [
    {
      object (RegionalPricingAndAvailabilityConfig)
    }
  ],
  "offerTags": [
    {
      object (OfferTag)
    }
  ],
  "regionsVersion": {
    object (RegionsVersion)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "preOrderOffer": {
    object (OneTimeProductPreOrderOffer)
  },
  "discountedOffer": {
    object (OneTimeProductDiscountedOffer)
  },
  "gameRewardOffer": {
    object (OneTimeProductGameRewardOffer)
  }
  // End of mutually exclusive fields.
}
欄位
packageName

string

必填。不可變動。上層產品所屬應用程式的套件名稱。
productId

string

必填。不可變動。這項商品所屬上層產品的 ID。
purchaseOptionId

string

必填。不可變動。此優惠擴充功能所屬的購買選項 ID。
offerId

string

必填。不可變動。這項產品優惠的 ID。不得重複用於購買選項。只能使用小寫字母 (a-z)、數字 (0-9) 和連字號 (-)，且開頭必須是數字或小寫字母。長度上限為 63 個半形字元。
state

enum (State)

僅供輸出。這項優惠的目前狀態。這個欄位無法透過更新資源變更。請改用專屬端點。
regionalPricingAndAvailabilityConfigs[]

object (RegionalPricingAndAvailabilityConfig)

這項商品的區域價格和供應情形資訊組合。項目不得重複，且必須具有相同的 regionCode。
offerTags[]

object (OfferTag)

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

object (RegionsVersion)

僅供輸出。用於產生單次產品優惠的區域設定版本。
這項優惠的類型。必須設定一個選項。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位：
preOrderOffer

object (OneTimeProductPreOrderOffer)

預購優惠。
discountedOffer

object (OneTimeProductDiscountedOffer)

折扣優惠。
gameRewardOffer

object (OneTimeProductGameRewardOffer)

遊戲獎勵優惠。
互斥欄位結束。

州

優惠的目前狀態。

列舉
STATE_UNSPECIFIED 預設值，不應使用。
DRAFT 延續過去做法，使用者無法享有這項優惠。
ACTIVE 只要符合條件，使用者就能享有這項優惠。
CANCELLED 此狀態僅適用於預購商品。優惠已取消，不再提供給使用者。與這項優惠相關的待處理訂單已取消。
INACTIVE 此狀態僅適用於折扣優惠。使用者無法再享有這項優惠。

OneTimeProductPreOrderOffer

預購優惠專用設定。

JSON 表示法 
{
  "startTime": string,
  "endTime": string,
  "releaseTime": string,
  "priceChangeBehavior": enum (PreOrderPriceChangeBehavior)
}
欄位
startTime

string (Timestamp format)

必填。預購開始時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
endTime

string (Timestamp format)

必填。預購停止提供時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
releaseTime

string (Timestamp format)

必填。與預購活動相關聯的產品發布時間，以及預購訂單的商品出貨時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
priceChangeBehavior

enum (PreOrderPriceChangeBehavior)

必填。不可變動。指定價格異動對既有預購訂單的影響。

PreOrderPriceChangeBehavior

指定價格異動對既有預購訂單的影響。

列舉
PRE_ORDER_PRICE_CHANGE_BEHAVIOR_UNSPECIFIED 未指定的價格異動行為。不得使用。
PRE_ORDER_PRICE_CHANGE_BEHAVIOR_TWO_POINT_LOWEST 系統會比較預購時的初始價格和推出日期時的最終優惠價格，兩者取其低後，向買家收費。
PRE_ORDER_PRICE_CHANGE_BEHAVIOR_NEW_ORDERS_ONLY 無論預購後價格是否異動，買家都會以預購時的價格付費。

OneTimeProductDiscountedOffer

折扣優惠專用設定。

JSON 表示法 
{
  "startTime": string,
  "endTime": string,
  "redemptionLimit": string
}
欄位
startTime

string (Timestamp format)

優惠開始生效時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
endTime

string (Timestamp format)

優惠停止提供時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
redemptionLimit

string (int64 format)

選用。這項優惠可兌換的次數。如果未設定或設為 0，表示可無限次兌換。否則必須是介於 1 到 50 之間的數字 (含這兩個數字)。

OneTimeProductGameRewardOffer

遊戲獎勵優惠專用設定。

JSON 表示法 
{
  "redemptionLimit": string
}
欄位
redemptionLimit

string (int64 format)

(選用步驟) 這項優惠可兌換的次數。如果未設定或設為 0，表示可無限次兌換。否則必須是介於 1 到 50 之間的數字 (含這兩個數字)。

RegionalPricingAndAvailabilityConfig

單次產品優惠的區域價格和供應情形設定。

JSON 表示法 
{
  "regionCode": string,
  "availability": enum (Availability),

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

string

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

enum (Availability)

必填。這個區域的供應情形。
這項優惠的價格覆寫。必須設定一個選項。以下是互斥欄位清單。回應中最多會設定下列其中一個欄位：
noOverride

object (OneTimeProductOfferNoPriceOverrideOptions)

系統會使用這個區域購買選項定義的價格。
relativeDiscount

number

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

object (Money)

從購買選項價格中扣除的折扣絕對值。

必須介於 0 和購買選項價格之間。
free

object

這項優惠不需付費。
互斥欄位結束。

OneTimeProductOfferNoPriceOverrideOptions

這個類型沒有任何欄位。

單次產品優惠方案選項，不附帶區域價格覆寫。

優惠適用性

優惠供應情況。

列舉
AVAILABILITY_UNSPECIFIED 未指定供應情形。不得使用。
AVAILABLE 這項優惠可提供給使用者。
NO_LONGER_AVAILABLE 使用者無法再享有這項優惠。只有先前將供應情形設為「AVAILABLE」時，才能使用這個值。

方法

activate

 啟用單次產品優惠。

batchDelete

 刪除一或多項單次產品優惠。

batchGet

 讀取一或多項單次產品優惠。

batchUpdate

 建立或更新一或多項單次產品優惠。

batchUpdateStates

 更新整批單次產品優惠狀態。

cancel

 取消單次產品優惠。

deactivate

 停用單次產品優惠。

list

 列出指定應用程式、產品或購買選項下的所有優惠。

錯誤代碼

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

錯誤代碼 原因 說明 解析度