Resource: Subscription

A subscription serves as a central billing entity between an external partner and Google. The underlying Google services rely on the subscription state to grant or revoke the user's service entitlement.

It's important to note that the subscription state may not always perfectly align with the user's service entitlement. For example, some Google services may continue providing access to the user until the current billing cycle ends, even if the subscription has been immediately canceled. However, other services may not do the same. To fully understand the specific details, please consult the relevant contract or product policy.

JSON representation

JSON representation
{ "name": string, "products": [ string ], "promotions": [ string ], "promotionSpecs": [ { object (`PromotionSpec`) } ], "partnerUserToken": string, "serviceLocation": { object (`Location`) }, "purchaseTime": string, "upgradeDowngradeDetails": { object (`UpgradeDowngradeDetails`) }, "redirectUri": string, "createTime": string, "updateTime": string, "cycleEndTime": string, "renewalTime": string, "freeTrialEndTime": string, "endUserEntitled": boolean, "state": enum (`State`), "processingState": enum (`ProcessingState`), "cancellationDetails": { object (`CancellationDetails`) }, "migrationDetails": { object (`MigrationDetails`) }, "lineItems": [ { object (`LineItem`) } ] }

{
  "name": string,
  "products": [
    string
  ],
  "promotions": [
    string
  ],
  "promotionSpecs": [
    {
      object (PromotionSpec)
    }
  ],
  "partnerUserToken": string,
  "serviceLocation": {
    object (Location)
  },
  "purchaseTime": string,
  "upgradeDowngradeDetails": {
    object (UpgradeDowngradeDetails)
  },
  "redirectUri": string,
  "createTime": string,
  "updateTime": string,
  "cycleEndTime": string,
  "renewalTime": string,
  "freeTrialEndTime": string,
  "endUserEntitled": boolean,
  "state": enum (State),
  "processingState": enum (ProcessingState),
  "cancellationDetails": {
    object (CancellationDetails)
  },
  "migrationDetails": {
    object (MigrationDetails)
  },
  "lineItems": [
    {
      object (LineItem)
    }
  ]
}

Fields
`name`	`string` Identifier. Resource name of the subscription. It will have the format of "partners/{partner_id}/subscriptions/{subscriptionId}". This is available for authorizeAddon, but otherwise is response only.
`products[]`	`string` Optional. Deprecated: consider using `lineItems` as the input. Required. Resource name that identifies the purchased products. The format will be 'partners/{partner_id}/products/{productId}'.
`promotions[]`	`string` Optional. Deprecated: consider using the top-level `promotionSpecs` as the input. Optional. Resource name that identifies one or more promotions that can be applied on the product. A typical promotion for a subscription is Free trial. The format will be 'partners/{partner_id}/promotions/{promotion_id}'.
`promotionSpecs[]`	`object (PromotionSpec)` Optional. Subscription-level promotions. Only free trial is supported on this level. It determines the first renewal time of the subscription to be the end of the free trial period. Specify the promotion resource name only when used as input.
`partnerUserToken`	`string` Required. Identifier of the end-user in partner’s system. The value is restricted to 63 ASCII characters at the maximum.
`serviceLocation`	`object (Location)` Required. The location that the service is provided as indicated by the partner.
`purchaseTime`	`string (Timestamp format)` Optional. The timestamp when the user transaction was made with the Partner. Specify for the case of "bundle with choice", and it must be before the provision_time (when the user makes a selection). 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"`.
`upgradeDowngradeDetails`	`object (UpgradeDowngradeDetails)` Optional. Details about the previous subscription that this new subscription upgrades/downgrades from. Only populated if this subscription is an upgrade/downgrade from another subscription.
`redirectUri`	`string` Output only. The place where partners should redirect the end-user to after creation. This field might also be populated when creation failed. However, Partners should always prepare a default URL to redirect the user in case this field is empty.
`createTime`	`string (Timestamp format)` Output only. System generated timestamp when the subscription is created. UTC timezone. 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"`.
`updateTime`	`string (Timestamp format)` Output only. System generated timestamp when the subscription is most recently updated. UTC timezone. 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"`.
`cycleEndTime`	`string (Timestamp format)` Output only. The time at which the subscription is expected to be extended, in ISO 8061 format. UTC timezone. For example: "2019-08-31T17:28:54.564Z" 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"`.
`renewalTime`	`string (Timestamp format)` Output only. The time at which the subscription is expected to be renewed by Google - a new charge will be incurred and the service entitlement will be renewed. A non-immediate cancellation will take place at this time too, before which, the service entitlement for the end user will remain valid. UTC timezone in ISO 8061 format. For example: "2019-08-31T17:28:54.564Z" 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"`.
`freeTrialEndTime`	`string (Timestamp format)` Output only. End of the free trial period, in ISO 8061 format. For example, "2019-08-31T17:28:54.564Z". It will be set the same as createTime if no free trial promotion is specified. 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"`.
`endUserEntitled`	`boolean` Output only. Indicates if the subscription is entitled to the end user.
`state`	`enum (State)` Output only. Describes the state of the subscription. See more details at the lifecycle of a subscription.
`processingState`	`enum (ProcessingState)` Output only. Describes the processing state of the subscription. See more details at the lifecycle of a subscription.
`cancellationDetails`	`object (CancellationDetails)` Output only. Describes the details of a cancelled subscription. Only applicable to subscription of state `STATE_CANCELLED`.
`migrationDetails`	`object (MigrationDetails)` Output only. Describes the details of the migrated subscription. Only populated if this subscription is migrated from another system.
`lineItems[]`	`object (LineItem)` Required. The line items of the subscription.

Location

Describes a location of an end user.

JSON representation
{ "regionCode": string, "postalCode": string }

Fields

Fields
`regionCode`	`string` 2-letter ISO region code for current content region. Ex. “US” Please refers to: https://en.wikipedia.org/wiki/ISO_3166-1
`postalCode`	`string` The postal code this location refers to. Ex. "94043"

regionCode

string

2-letter ISO region code for current content region. Ex. “US” Please refers to: https://en.wikipedia.org/wiki/ISO_3166-1

postalCode

string

The postal code this location refers to. Ex. "94043"

UpgradeDowngradeDetails

Details about the previous subscription that this new subscription upgrades/downgrades from.

JSON representation
{ "previousSubscriptionId": string, "billingCycleSpec": enum (`BillingCycleSpec`) }

Fields

Fields
`previousSubscriptionId`	`string` Required. The previous subscription id to be replaced. The format can be one of the following: `subscriptionId`: the old subscription id under the same partner_id. `partners/{partner_id}/subscriptions/{subscriptionId}`. A different partner_id is allowed. But they must be under the same partner group.
`billingCycleSpec`	`enum (BillingCycleSpec)` Required. Specifies the billing cycle spec for the new upgraded/downgraded subscription.

previousSubscriptionId

string

Required. The previous subscription id to be replaced. The format can be one of the following:

subscriptionId: the old subscription id under the same partner_id.
partners/{partner_id}/subscriptions/{subscriptionId}. A different partner_id is allowed. But they must be under the same partner group.

billingCycleSpec

enum (BillingCycleSpec)

Required. Specifies the billing cycle spec for the new upgraded/downgraded subscription.

BillingCycleSpec

Specifies the billing cycle spec for the new upgraded/downgraded subscription.

Enums
`BILLING_CYCLE_SPEC_UNSPECIFIED`	Billing cycle spec is not specified.
`BILLING_CYCLE_SPEC_ALIGN_WITH_PREVIOUS_SUBSCRIPTION`	The billing cycle of the new subscription starts immediately but aligns with the previous subscription it upgrades or downgrades from. First cycle of the new subscription will be prorated.
`BILLING_CYCLE_SPEC_START_IMMEDIATELY`	The billing cycle of the new subscription starts immediately.
`BILLING_CYCLE_SPEC_DEFERRED_TO_NEXT_RECURRENCE`	The billing cycle starts at the end of the previous subscription's billing cycle and aligns with the previous subscription's billing cycle.

State

The state of a subscription.

Enums
`STATE_UNSPECIFIED`	The state is unspecified.
`STATE_CREATED`	The subscription is created, a state before it is moved to STATE_ACTIVE.
`STATE_ACTIVE`	The subscription is active.
`STATE_CANCELLED`	The subscription is cancelled. This is the final state of the subscription, as it can no longer be modified or reactivated.
`STATE_IN_GRACE_PERIOD`	The subscription is in grace period. It can happen: 1) in manual extend mode, the subscription is not extended by the partner at the end of current cycle. 2) for outbound authorization enabled partners, a renewal purchase order is rejected.
`STATE_CANCEL_AT_END_OF_CYCLE`	The subscription is waiting to be cancelled by the next recurrence cycle.
`STATE_SUSPENDED`	The subscription is suspended.

ProcessingState

The processing state of a subscription which is transient.

Enums
`PROCESSING_STATE_UNSPECIFIED`	The processing state is unspecified.
`PROCESSING_STATE_CANCELLING`	The subscription is being cancelled.
`PROCESSING_STATE_RECURRING`	The subscription is recurring.
`PROCESSING_STATE_RESUMING`	The subscription is being resumed.

CancellationDetails

Describes the details of a cancelled or cancelling subscription.

JSON representation
{ "reason": enum (`CancellationReason`) }

Fields

Fields
`reason`	`enum (CancellationReason)` Output only. The reason of the cancellation.

reason

enum (CancellationReason)

Output only. The reason of the cancellation.

CancellationReason

Describes the reason for cancellation of the subscription.

Enums
`CANCELLATION_REASON_UNSPECIFIED`	Reason is unspecified. Should not be used.
`CANCELLATION_REASON_FRAUD`	Fraudualant transaction.
`CANCELLATION_REASON_REMORSE`	Buyer's remorse.
`CANCELLATION_REASON_ACCIDENTAL_PURCHASE`	Accidential purchase.
`CANCELLATION_REASON_PAST_DUE`	Payment is past due.
`CANCELLATION_REASON_ACCOUNT_CLOSED`	Used for notification only, do not use in Cancel API. User account closed.
`CANCELLATION_REASON_UPGRADE_DOWNGRADE`	Used for notification only, do not use in Cancel API. Cancellation due to upgrade or downgrade.
`CANCELLATION_REASON_USER_DELINQUENCY`	Cancellation due to user delinquency
`CANCELLATION_REASON_SYSTEM_ERROR`	Used for notification only, do not use in Cancel API. Cancellation due to an unrecoverable system error.
`CANCELLATION_REASON_SYSTEM_CANCEL`	Used for notification only, do not use in Cancel API. The subscription is cancelled by Google automatically since it is no longer valid.
`CANCELLATION_REASON_BILLING_SYSTEM_SWITCH`	Cancellation due to a billing system switch.
`CANCELLATION_REASON_OTHER`	Other reason.

MigrationDetails

Describes the details of the migrated subscription.

JSON representation
{ "migratedSubscriptionId": string }

Fields

Fields
`migratedSubscriptionId`	`string` Output only. The migrated subscription id in the legacy system.

migratedSubscriptionId

string

Output only. The migrated subscription id in the legacy system.

Methods
`authorizeAddon`	Currently, it is used by only YouTube partners.
`authorizeSignup`	Currently, this API is not yet enabled.
`cancel`	Cancels a subscription service either immediately or by the end of the current billing cycle for their customers.
`create`	Used by partners to create a subscription for their customers.
`entitle`	Entitles a previously provisioned subscription to the current end user.
`extend`	[Opt-in only] Most partners should be on auto-extend by default.
`get`	Gets a subscription by id.
`provision`	Used by partners to provision a subscription for their customers.
`resume`	Resumes a suspended subscription.
`suspend`	Suspends a subscription.
`undoCancel`	Currently, it is used by Google One, Play Pass partners.

REST Resource: partners.subscriptions

Resource: Subscription

Location

UpgradeDowngradeDetails

BillingCycleSpec

State

ProcessingState

CancellationDetails

CancellationReason

MigrationDetails

Methods

`authorizeAddon`

`authorizeSignup`

`cancel`

`create`

`entitle`

`extend`

`get`

`provision`

`resume`

`suspend`

`undoCancel`

REST Resource: partners.subscriptions Stay organized with collections Save and categorize content based on your preferences.

Resource: Subscription

Location

UpgradeDowngradeDetails

BillingCycleSpec

State

ProcessingState

CancellationDetails

CancellationReason

MigrationDetails

Methods

REST Resource: partners.subscriptions