REST Resource: partners.subscriptions

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 
{
  "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 uses 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 uses 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 uses 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 uses 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 uses 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 uses 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.

PromotionSpec

Describes the spec for one promotion.

JSON representation 
{
  "promotion": string,
  "type": enum (PromotionType),

  // Union field spec can be only one of the following:
  "introductoryPricingDetails": {
    object (IntroductoryPricingDetails)
  },
  "freeTrialDuration": {
    object (Duration)
  }
  // End of list of possible types for union field spec.
}
Fields
promotion

string

Required. Promotion resource name that identifies a promotion. The format is 'partners/{partner_id}/promotions/{promotion_id}'.
type

enum (PromotionType)

Output only. The type of the promotion for the spec.

Union field spec.

spec can be only one of the following:
introductoryPricingDetails

object (IntroductoryPricingDetails)

Output only. The details of the introductory pricing spec if the promotion is of type INTRODUCTORY_PRICING.
freeTrialDuration

object (Duration)

Output only. The duration of the free trial if the promotion is of type FREE_TRIAL.

Location

Describes a location of an end user.

JSON representation 
{
  "regionCode": string,
  "postalCode": string
}
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"

UpgradeDowngradeDetails

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

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

string

Required. The previous subscription id to be replaced. This is not the full resource name, use the subscriptionId segment only.
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.

CancellationDetails

Describes the details of a cancelled or cancelling subscription.

JSON representation 
{
  "reason": enum (CancellationReason)
}
Fields
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_OTHER Other reason.

MigrationDetails

Describes the details of the migrated subscription.

JSON representation 
{
  "migratedSubscriptionId": string
}
Fields
migratedSubscriptionId

string

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

LineItem

Individual line item definition of a subscription.

JSON representation 
{
  "product": string,
  "description": string,
  "lineItemPromotionSpecs": [
    {
      object (PromotionSpec)
    }
  ],
  "state": enum (LineItemState),
  "lineItemFreeTrialEndTime": string,
  "recurrenceType": enum (LineItemRecurrenceType),
  "oneTimeRecurrenceDetails": {
    object (OneTimeRecurrenceDetails)
  },
  "productPayload": {
    object (ProductPayload)
  },
  "amount": {
    object (Amount)
  },
  "bundleDetails": {
    object (BundleDetails)
  },
  "finiteBillingCycleDetails": {
    object (FiniteBillingCycleDetails)
  },
  "lineItemIndex": integer
}
Fields
product

string

Required. Product resource name that identifies one the line item The format is 'partners/{partner_id}/products/{productId}'.
description

string

Output only. Description of this line item.
lineItemPromotionSpecs[]

object (PromotionSpec)

Optional. The promotions applied on the line item. It can be:

  • an introductory pricing promotion.
  • a free trial promotion. This feature is not enabled. If used, the request will be rejected.

When used as input in Create or Provision API, specify its resource name only.
state

enum (LineItemState)

Output only. The state of the line item.
lineItemFreeTrialEndTime

string (Timestamp format)

Output only. The free trial end time will be populated after the line item is successfully processed. End time of the line item 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 uses 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".
recurrenceType

enum (LineItemRecurrenceType)

Output only. The recurrence type of the line item.
oneTimeRecurrenceDetails

object (OneTimeRecurrenceDetails)

Output only. Details only set for a ONE_TIME recurrence line item.
productPayload

object (ProductPayload)

Optional. Product specific payload for this line item.
amount

object (Amount)

Output only. The price of the product/service in this line item. The amount could be the wholesale price, or it can include a cost of sale based on the contract.
bundleDetails

object (BundleDetails)

Output only. The bundle details for the line item. Only populated if the line item corresponds to a hard bundle.
finiteBillingCycleDetails

object (FiniteBillingCycleDetails)

Optional. Details for a subscription line item with finite billing cycles. If unset, the line item will be charged indefinitely. Used only with LINE_ITEM_RECURRENCE_TYPE_PERIODIC.
lineItemIndex

integer

Output only. A unique index of the subscription line item.

LineItemState

The state of a subscription line item.

Enums
LINE_ITEM_STATE_UNSPECIFIED Unspecified state.
LINE_ITEM_STATE_ACTIVE The line item is in ACTIVE state. If the subscription is cancelled or suspended, the line item will not be charged even if the line item is active.
LINE_ITEM_STATE_INACTIVE The line item is in INACTIVE state.
LINE_ITEM_STATE_NEW The line item is new, and is not activated or charged yet.
LINE_ITEM_STATE_ACTIVATING The line item is being activated in order to be charged. If a free trial applies to the line item, the line item is pending a prorated charge at the end of the free trial period, as indicated by lineItemFreeTrialEndTime.
LINE_ITEM_STATE_DEACTIVATING The line item is being deactivated, and a prorated refund in being processed.
LINE_ITEM_STATE_WAITING_TO_DEACTIVATE The line item is scheduled to be deactivated at the end of the current cycle.
LINE_ITEM_STATE_OFF_CYCLE_CHARGING Line item is being charged off-cycle.

LineItemRecurrenceType

The recurrence type of the line item.

Enums
LINE_ITEM_RECURRENCE_TYPE_UNSPECIFIED The line item recurrence type is unspecified.
LINE_ITEM_RECURRENCE_TYPE_PERIODIC The line item recurs periodically.
LINE_ITEM_RECURRENCE_TYPE_ONE_TIME The line item does not recur in the future.

OneTimeRecurrenceDetails

Details for a ONE_TIME recurrence line item.

JSON representation 
{
  "servicePeriod": {
    object (ServicePeriod)
  }
}
Fields
servicePeriod

object (ServicePeriod)

Output only. The service period of the ONE_TIME line item.

ProductPayload

Specifies product specific payload.

JSON representation 
{
  "googleOnePayload": {
    object (GoogleOnePayload)
  },
  "youtubePayload": {
    object (YoutubePayload)
  },
  "googleHomePayload": {
    object (GoogleHomePayload)
  }
}
Fields
googleOnePayload

object (GoogleOnePayload)

Product-specific payloads. Payload specific to Google One products.
youtubePayload

object (YoutubePayload)

Payload specific to Youtube products.
googleHomePayload

object (GoogleHomePayload)

Payload specific to Google Home products.

GoogleOnePayload

Payload specific to Google One products.

JSON representation 
{
  "campaigns": [
    string
  ],
  "salesChannel": enum (Channel),
  "storeId": string,
  "offering": enum (Offering)
}
Fields
campaigns[]

string

Campaign attributed to sales of this subscription.
salesChannel

enum (Channel)

The type of sales channel through which the subscription was sold.
storeId

string

The identifier for the partner store where the subscription was sold.
offering

enum (Offering)

The type of offering the subscription was sold by the partner. e.g. VAS.

Channel

Describes the channel through which the subscription was sold by partner.

Enums
CHANNEL_UNSPECIFIED The channel type is unspecified.
CHANNEL_RETAIL Sold at store.
CHANNEL_ONLINE_WEB Sold through partner website.
CHANNEL_ONLINE_ANDROID_APP Sold through partner android app.
CHANNEL_ONLINE_IOS_APP Sold through partner iOS app.

Offering

Describes the type of partner offering the subscription was part of.

Enums
OFFERING_UNSPECIFIED The type of partner offering is unspecified.
OFFERING_VAS_BUNDLE Google One product purchased as a Value added service in addition to existing partner's products. Customer pays additional amount for Google One product.
OFFERING_VAS_STANDALONE Google One product purchased by itself by customer as a value add service. Customer pays additional amount for Google One product.
OFFERING_HARD_BUNDLE Product purchased as part of a hard bundle where Google One was included with the bundle. Google One pricing is included in the bundle.
OFFERING_SOFT_BUNDLE Purchased as part of a bundle where Google One was provided as an option. Google One pricing is included in the bundle.

YoutubePayload

Payload specific to Youtube products.

JSON representation 
{
  "partnerEligibilityIds": [
    string
  ],
  "accessEndTime": string,
  "partnerPlanType": enum (PartnerPlanType)
}
Fields
partnerEligibilityIds[]

string

The list of eligibility_ids which are applicable for the line item.
accessEndTime

string (Timestamp format)

Output only. The access expiration time for this line item.

Uses RFC 3339, where generated output will always be Z-normalized and uses 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".
partnerPlanType

enum (PartnerPlanType)

Optional. Specifies the plan type offered to the end user by the partner.

PartnerPlanType

Partner side plan type.

Enums
PARTNER_PLAN_TYPE_UNSPECIFIED Unspecified. Should not use, reserved as an invalid value.
PARTNER_PLAN_TYPE_STANDALONE This item is offered as a standalone product to the user.
PARTNER_PLAN_TYPE_HARD_BUNDLE This item is bundled with another partner offering, the item is provisioned at purchase time.
PARTNER_PLAN_TYPE_SOFT_BUNDLE This item is bundled with another partner offering, the item is provisioned after puchase, when the user opts in this Google service.

GoogleHomePayload

Payload specific for Google Home products.

JSON representation 
{
  "partnerStructureId": string,
  "attachedToGoogleStructure": boolean
}
Fields
partnerStructureId

string

Optional. This identifies the structure ID on partner side that the subscription should be applied to. Only required when the partner requires structure mapping.
attachedToGoogleStructure

boolean

Output only. This identifies whether the subscription is attached to a Google Home structure.

BundleDetails

The bundle details for a line item corresponding to a hard bundle.

JSON representation 
{
  "bundleElementDetails": [
    {
      object (BundleElementDetails)
    }
  ]
}
Fields
bundleElementDetails[]

object (BundleElementDetails)

Output only. The details for each element in the hard bundle.

BundleElementDetails

The details for an element in the hard bundle.

JSON representation 
{
  "product": string,
  "userAccountLinkedTime": string
}
Fields
product

string

Output only. Product resource name that identifies the bundle element. The format is 'partners/{partner_id}/products/{productId}'.
userAccountLinkedTime

string (Timestamp format)

Output only. The time when this product is linked to an end user.

Uses RFC 3339, where generated output will always be Z-normalized and uses 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".

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.