REST Resource: monetization.onetimeproducts.purchaseOptions.offers

  • OneTimeProductOffer represents a single offer for a one-time product with details like package name, product ID, and offer ID.

  • Offers have a state indicating their availability, such as DRAFT, ACTIVE, CANCELLED, or INACTIVE.

  • Offers can be configured as pre-order offers with specific start, end, and release times, or as discounted offers with start and end times and an optional redemption limit.

  • Regional configurations allow defining pricing and availability for offers in specific regions, including using the base purchase option price, a relative discount, or an absolute discount.

  • The resource provides methods for activating, batch deleting, batch getting, batch updating, batch updating states, canceling, deactivating, and listing one-time product offers.

Resource: OneTimeProductOffer

A single offer for a one-time product.

JSON representation 
{
  "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.
}
Fields
packageName

string

Required. Immutable. The package name of the app the parent product belongs to.
productId

string

Required. Immutable. The ID of the parent product this offer belongs to.
purchaseOptionId

string

Required. Immutable. The ID of the purchase option to which this offer is an extension.
offerId

string

Required. Immutable. The ID of this product offer. Must be unique within the purchase option. It must start with a number or lower-case letter, and can only contain lower-case letters (a-z), numbers (0-9), and hyphens (-). The maximum length is 63 characters.
state

enum (State)

Output only. The current state of this offer. This field cannot be changed by updating the resource. Use the dedicated endpoints instead.
regionalPricingAndAvailabilityConfigs[]

object (RegionalPricingAndAvailabilityConfig)

Set of regional pricing and availability information for this offer. Must not have duplicate entries with the same regionCode.
offerTags[]

object (OfferTag)

Optional. List of up to 20 custom tags specified for this offer, and returned to the app through the billing library.
regionsVersion

object (RegionsVersion)

Output only. The version of the regions configuration that was used to generate the one-time product offer.
The type of this offer. Exactly one must be set. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
preOrderOffer

object (OneTimeProductPreOrderOffer)

A pre-order offer.
discountedOffer

object (OneTimeProductDiscountedOffer)

A discounted offer.
gameRewardOffer

object (OneTimeProductGameRewardOffer)

A game reward offer.
End of mutually exclusive fields.

State

The current state of the offer.

Enums
STATE_UNSPECIFIED Default value, should never be used.
DRAFT The offer is not and has never been available to users.
ACTIVE The offer is available to users, as long as its conditions are met.
CANCELLED This state is specific to pre-orders. The offer is cancelled and not available to users. All pending orders related to this offer were cancelled.
INACTIVE This state is specific to discounted offers. The offer is no longer available to users.

OneTimeProductPreOrderOffer

Configuration specific to pre-order offers.

JSON representation 
{
  "startTime": string,
  "endTime": string,
  "releaseTime": string,
  "priceChangeBehavior": enum (PreOrderPriceChangeBehavior)
}
Fields
startTime

string (Timestamp format)

Required. Time when the pre-order will start being available.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Required. Time when the pre-order will stop being available.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
releaseTime

string (Timestamp format)

Required. Time on which the product associated with the pre-order will be released and the pre-order orders fulfilled.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
priceChangeBehavior

enum (PreOrderPriceChangeBehavior)

Required. Immutable. Specifies how price changes affect pre-existing pre-orders.

PreOrderPriceChangeBehavior

Specifies how price changes affect pre-existing pre-orders.

Enums
PRE_ORDER_PRICE_CHANGE_BEHAVIOR_UNSPECIFIED Unspecified price change behavior. Must not be used.
PRE_ORDER_PRICE_CHANGE_BEHAVIOR_TWO_POINT_LOWEST The buyer gets charged the minimum between the initial price at the time of pre-order and the final offer price on the release date.
PRE_ORDER_PRICE_CHANGE_BEHAVIOR_NEW_ORDERS_ONLY The buyer gets the same price as the one they pre-ordered, regardless of any price changes that may have happened after the pre-order.

OneTimeProductDiscountedOffer

Configuration specific to discounted offers.

JSON representation 
{
  "startTime": string,
  "endTime": string,
  "redemptionLimit": string
}
Fields
startTime

string (Timestamp format)

Time when the offer will start being available.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Time when the offer will stop being available.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
redemptionLimit

string (int64 format)

Optional. The number of times this offer can be redeemed. If unset or set to 0, allows for unlimited offer redemptions. Otherwise must be a number between 1 and 50 inclusive.

OneTimeProductGameRewardOffer

Configuration specific to game reward offers.

JSON representation 
{
  "redemptionLimit": string
}
Fields
redemptionLimit

string (int64 format)

Optional. The number of times this offer can be redeemed. If unset or set to 0, allows for unlimited offer redemptions. Otherwise must be a number between 1 and 50 inclusive.

RegionalPricingAndAvailabilityConfig

Regional pricing and availability configuration for a one-time product offer.

JSON representation 
{
  "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.
}
Fields
regionCode

string

Required. Region code this configuration applies to, as defined by ISO 3166-2, e.g., "US".
availability

enum (Availability)

Required. The availability for this region.
The price override of this offer. Exactly one must be set. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
noOverride

object (OneTimeProductOfferNoPriceOverrideOptions)

The price defined in the purchase option for this region will be used.
relativeDiscount

number

The percentage discount subtracted from the purchase option price, specified as a fraction strictly larger than 0 and strictly smaller than 1. For example, a value of 0.8 represents an 80% discount, meaning that if the purchase option price is $100, the offer price will be $20. The resulting price will be rounded to the nearest billable unit (e.g. cents for USD). The relative discount is considered invalid if the discounted price ends up being smaller than the minimum price allowed in this region.
absoluteDiscount

object (Money)

The absolute value of the discount that is subtracted from the purchase option price.

It should be between 0 and the purchase option price.
free

object

The offer is free.
End of mutually exclusive fields.

OneTimeProductOfferNoPriceOverrideOptions

This type has no fields.

Options for one-time product offers without a regional price override.

Availability

The availability of the offer.

Enums
AVAILABILITY_UNSPECIFIED Unspecified availability. Must not be used.
AVAILABLE The offer is available to users.
NO_LONGER_AVAILABLE The offer is no longer available to users. This value can only be used if the availability was previously set as AVAILABLE.

Methods

activate

 Activates a one-time product offer.

batchDelete

 Deletes one or more one-time product offers.

batchGet

 Reads one or more one-time product offers.

batchUpdate

 Creates or updates one or more one-time product offers.

batchUpdateStates

 Updates a batch of one-time product offer states.

cancel

 Cancels a one-time product offer.

deactivate

 Deactivates a one-time product offer.

list

 Lists all offers under a given app, product, or purchase option.

Error codes

The operations of this resource, return the following HTTP error codes:

Error code Reason Description Resolution