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

  // Union field offer_type can be only one of the following:
  "preOrderOffer": {
    object (OneTimeProductPreOrderOffer)
  },
  "discountedOffer": {
    object (OneTimeProductDiscountedOffer)
  }
  // End of list of possible types for union field offer_type.
}
欄位
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)

僅供輸出。用於產生單次產品優惠的區域設定版本。
聯集欄位 offer_type。這項優惠的類型。必須設定一個選項。offer_type 只能是下列其中一項：
preOrderOffer

object (OneTimeProductPreOrderOffer)

預購優惠。
discountedOffer

object (OneTimeProductDiscountedOffer)

折扣優惠。

狀態

優惠的目前狀態。

列舉
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 之間的數字 (含這兩個數字)。

RegionalPricingAndAvailabilityConfig

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

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

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

string

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

enum (Availability)

必填。這個區域的供應情形。
聯集欄位 price_override。這項優惠的價格覆寫。必須設定一個選項。price_override 只能是下列之一：
noOverride

object (OneTimeProductOfferNoPriceOverrideOptions)

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

number

使用者為這項優惠支付的購買選項價格比例。舉例來說，如果這個區域的購買選項價格為 $12 美元，50% 的折扣就相當於 $6 美元。折扣比例必須指定為大於 0 且小於 1 的分數。計算出的價格會四捨五入至最接近的可計費單位 (例如「美分」)。如果折扣價低於該地區允許的最低價格，相對折扣就會視為無效。
absoluteDiscount

object (Money)

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

應介於 0 和購買選項價格之間。

OneTimeProductOfferNoPriceOverrideOptions

這個類型沒有任何欄位。

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

優惠適用性

優惠供應情況。

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

方法

activate

 啟用單次產品優惠。

batchDelete

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

batchGet

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

batchUpdate

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

batchUpdateStates

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

cancel

 取消單次產品優惠。

deactivate

 停用單次產品優惠。

list

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

錯誤代碼

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

錯誤代碼 原因 說明 解決方法
400 invalidValue 要求中提供的值無效。如果購買權杖格式有誤或無效，通常會傳回這個錯誤。 根據 API 參考資料，更正要求主體或參數中的無效欄位值。
400 required 要求缺少必要欄位或參數。 請參閱 API 說明文件，確認已包含所有必填欄位和參數。
403 userInsufficientPermission 使用者沒有足夠的權限可執行要求作業。 確認已驗證的使用者在 Google Play 管理中心具備必要權限。詳情請參閱「 使用服務帳戶」。
404 notFound 找不到要求的資源。 確認 ID (例如購買憑證、套件名稱、產品 ID、訂閱 ID) 正確無誤。
409 concurrentUpdate 嘗試更新正在同步更新的物件。 以指數輪詢方式重試要求。請避免同時修改相同資源。
5xx Generic error Google Play 伺服器發生一般錯誤。 請重試要求。

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