REST Resource: monetization.subscriptions.basePlans.offers

Resource: SubscriptionOffer

A single, temporary offer

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

string

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

string

Required. Immutable. The ID of the parent subscription this offer belongs to.
basePlanId

string

Required. Immutable. The ID of the base plan to which this offer is an extension.
offerId

string

Required. Immutable. Unique ID of this subscription offer. Must be unique within the base plan.
state

enum (State)

Output only. The current state of this offer. Can be changed using Activate and Deactivate actions. NB: the base plan state supersedes this state, so an active offer may not be available if the base plan is not active.
phases[]

object (SubscriptionOfferPhase)

Required. The phases of this subscription offer. Must contain at least one and at most two entries. Users will always receive all these phases in the specified order.
targeting

object (SubscriptionOfferTargeting)

The requirements that users need to fulfil to be eligible for this offer. Represents the requirements that Play will evaluate to decide whether an offer should be returned. Developers may further filter these offers themselves.
regionalConfigs[]

object (RegionalSubscriptionOfferConfig)

Required. The region-specific configuration of this offer. Must contain at least one entry.
otherRegionsConfig

object (OtherRegionsSubscriptionOfferConfig)

The configuration for any new locations Play may launch in the future.
offerTags[]

object (OfferTag)

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

State

The current state of the subscription offer.

Enums
STATE_UNSPECIFIED Default value, should never be used.
DRAFT The subscription offer is not and has never been available to users.
ACTIVE The subscription offer is available to new and existing users.
INACTIVE The subscription offer is not available to new users. Existing users retain access.

SubscriptionOfferPhase

A single phase of a subscription offer.

JSON representation 
{
  "recurrenceCount": integer,
  "duration": string,
  "regionalConfigs": [
    {
      object (RegionalSubscriptionOfferPhaseConfig)
    }
  ],
  "otherRegionsConfig": {
    object (OtherRegionsSubscriptionOfferPhaseConfig)
  }
}
Fields
recurrenceCount

integer

Required. The number of times this phase repeats. If this offer phase is not free, each recurrence charges the user the price of this offer phase.
duration

string

Required. The duration of a single recurrence of this phase. Specified in ISO 8601 format.
regionalConfigs[]

object (RegionalSubscriptionOfferPhaseConfig)

Required. The region-specific configuration of this offer phase. This list must contain exactly one entry for each region for which the subscription offer has a regional config.
otherRegionsConfig

object (OtherRegionsSubscriptionOfferPhaseConfig)

Pricing information for any new locations Play may launch in.

RegionalSubscriptionOfferPhaseConfig

Configuration for a single phase of a subscription offer in a single region.

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

string

Required. Immutable. The region to which this config applies.
Union field price_override. The price override of this phase. Required. price_override can be only one of the following:
price

object (Money)

The absolute price the user pays for this offer phase. The price must not be smaller than the minimum price allowed for this region.
relativeDiscount

number

The fraction of the base plan price prorated over the phase duration that the user pays for this offer phase. For example, if the base plan price for this region is $12 for a period of 1 year, then a 50% discount for a phase of a duration of 3 months would correspond to a price of $1.50. The discount must be specified as a fraction strictly larger than 0 and strictly smaller than 1. 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 amount of money subtracted from the base plan price prorated over the phase duration that the user pays for this offer phase. For example, if the base plan price for this region is $12 for a period of 1 year, then a $1 absolute discount for a phase of a duration of 3 months would correspond to a price of $2. The resulting price may not be smaller than the minimum price allowed for this region.
free

object (RegionalSubscriptionOfferPhaseFreePriceOverride)

Set to specify this offer is free to obtain.

RegionalSubscriptionOfferPhaseFreePriceOverride

This type has no fields.

Represents the free price override configuration for a single phase of a subscription offer

OtherRegionsSubscriptionOfferPhaseConfig

Configuration for any new locations Play may launch in for a single offer phase.

JSON representation 
{

  // 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.
}
Fields
Union field price_override. The price override of this phase. Required. price_override can be only one of the following:
otherRegionsPrices

object (OtherRegionsSubscriptionOfferPhasePrices)

The absolute price the user pays for this offer phase. The price must not be smaller than the minimum price allowed for any new locations Play may launch in.
relativeDiscount

number

The fraction of the base plan price prorated over the phase duration that the user pays for this offer phase. For example, if the base plan price for this region is $12 for a period of 1 year, then a 50% discount for a phase of a duration of 3 months would correspond to a price of $1.50. The discount must be specified as a fraction strictly larger than 0 and strictly smaller than 1. 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 any new locations Play may launch in.
absoluteDiscounts

object (OtherRegionsSubscriptionOfferPhasePrices)

The absolute amount of money subtracted from the base plan price prorated over the phase duration that the user pays for this offer phase. For example, if the base plan price for this region is $12 for a period of 1 year, then a $1 absolute discount for a phase of a duration of 3 months would correspond to a price of $2. The resulting price may not be smaller than the minimum price allowed for any new locations Play may launch in.
free

object (OtherRegionsSubscriptionOfferPhaseFreePriceOverride)

Set to specify this offer is free to obtain.

OtherRegionsSubscriptionOfferPhasePrices

Pricing information for any new locations Play may launch in.

JSON representation 
{
  "usdPrice": {
    object (Money)
  },
  "eurPrice": {
    object (Money)
  }
}
Fields
usdPrice

object (Money)

Required. Price in USD to use for any new locations Play may launch in.
eurPrice

object (Money)

Required. Price in EUR to use for any new locations Play may launch in.

OtherRegionsSubscriptionOfferPhaseFreePriceOverride

This type has no fields.

Represents the free price override configuration for any new locations Play may launch for a single offer phase.

SubscriptionOfferTargeting

Defines the rule a user needs to satisfy to receive this offer.

JSON representation 
{

  // 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.
}
Fields
Union field rule. Leave empty for developer-determined offer eligibility. rule can be only one of the following:
acquisitionRule

object (AcquisitionTargetingRule)

Offer targeting rule for new user acquisition.
upgradeRule

object (UpgradeTargetingRule)

Offer targeting rule for upgrading users' existing plans.

AcquisitionTargetingRule

Represents a targeting rule of the form: User never had {scope} before.

JSON representation 
{
  "scope": {
    object (TargetingRuleScope)
  }
}
Fields
scope

object (TargetingRuleScope)

Required. The scope of subscriptions this rule considers. Only allows "this subscription" and "any subscription in app".

TargetingRuleScope

Defines the scope of subscriptions which a targeting rule can match to target offers to users based on past or current entitlement.

JSON representation 
{

  // 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.
}
Fields

Union field scope.

scope can be only one of the following:
thisSubscription

object (TargetingRuleScopeThisSubscription)

The scope of the current targeting rule is the subscription in which this offer is defined.
anySubscriptionInApp

object (TargetingRuleScopeAnySubscriptionInApp)

The scope of the current targeting rule is any subscription in the parent app.
specificSubscriptionInApp

string

The scope of the current targeting rule is the subscription with the specified subscription ID. Must be a subscription within the same parent app.

TargetingRuleScopeThisSubscription

This type has no fields.

Represents the targeting rule scope corresponding to the subscriptions in which this offer is defined.

TargetingRuleScopeAnySubscriptionInApp

This type has no fields.

Represents the targeting rule scope corresponding to any subscription in the parent app.

UpgradeTargetingRule

Represents a targeting rule of the form: User currently has {scope} [with billing period {billing_period}].

JSON representation 
{
  "oncePerUser": boolean,
  "scope": {
    object (TargetingRuleScope)
  },
  "billingPeriodDuration": string
}
Fields
oncePerUser

boolean

Limit this offer to only once per user. If set to true, a user can never be eligible for this offer again if they ever subscribed to this offer.
scope

object (TargetingRuleScope)

Required. The scope of subscriptions this rule considers. Only allows "this subscription" and "specific subscription in app".
billingPeriodDuration

string

The specific billing period duration, specified in ISO 8601 format, that a user must be currently subscribed to to be eligible for this rule. If not specified, users subscribed to any billing period are matched.

RegionalSubscriptionOfferConfig

Configuration for a subscription offer in a single region.

JSON representation 
{
  "regionCode": string,
  "newSubscriberAvailability": boolean
}
Fields
regionCode

string

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

boolean

Whether the subscription offer in the specified region is available for new subscribers. Existing subscribers will not have their subscription cancelled if this value is set to false. If not specified, this will default to false.

OtherRegionsSubscriptionOfferConfig

Configuration for any new locations Play may launch in specified on a subscription offer.

JSON representation 
{
  "otherRegionsNewSubscriberAvailability": boolean
}
Fields
otherRegionsNewSubscriberAvailability

boolean

Whether the subscription offer in any new locations Play may launch in the future. If not specified, this will default to false.

Methods

activate

 Activates a subscription offer.

batchGet

 Reads one or more subscription offers.

batchUpdate

 Updates a batch of subscription offers.

batchUpdateStates

 Updates a batch of subscription offer states.

create

 Creates a new subscription offer.

deactivate

 Deactivates a subscription offer.

delete

 Deletes a subscription offer.

get

 Reads a single offer

list

 Lists all offers under a given subscription.

patch

 Updates an existing subscription offer.