- Resource: Subscription
- PromotionSpec
- Location
- UpgradeDowngradeDetails
- BillingCycleSpec
- State
- ProcessingState
- CancellationDetails
- CancellationReason
- LineItem
- LineItemState
- LineItemRecurrenceType
- OneTimeRecurrenceDetails
- ProductPayload
- GoogleOnePayload
- Channel
- Offering
- YoutubePayload
- PartnerPlanType
- BundleDetails
- BundleElementDetails
- Methods
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 ( |
Fields | |
---|---|
name |
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[] |
Optional. Deprecated: consider using |
promotions[] |
Optional. Deprecated: consider using the top-level |
promotionSpecs[] |
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 |
Required. Identifier of the end-user in partner’s system. The value is restricted to 63 ASCII characters at the maximum. |
serviceLocation |
Required. The location that the service is provided as indicated by the partner. |
purchaseTime |
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). A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
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 |
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 |
Output only. System generated timestamp when the subscription is created. UTC timezone. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
updateTime |
Output only. System generated timestamp when the subscription is most recently updated. UTC timezone. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
cycleEndTime |
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" A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
renewalTime |
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" A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
freeTrialEndTime |
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. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
endUserEntitled |
Output only. Indicates if the subscription is entitled to the end user. |
state |
Output only. Describes the state of the subscription. See more details at the lifecycle of a subscription. |
processingState |
Output only. Describes the processing state of the subscription. See more details at the lifecycle of a subscription. |
cancellationDetails |
Output only. Describes the details of a cancelled subscription. Only applicable to subscription of state |
lineItems[] |
Required. The line items of the subscription. |
PromotionSpec
Describes the spec for one promotion.
JSON representation |
---|
{ "promotion": string, "type": enum ( |
Fields | |
---|---|
promotion |
Required. Promotion resource name that identifies a promotion. The format is 'partners/{partner_id}/promotions/{promotion_id}'. |
type |
Output only. The type of the promotion for the spec. |
Union field
|
|
introductoryPricingDetails |
Output only. The details of the introductory pricing spec if the promotion is of type INTRODUCTORY_PRICING. |
freeTrialDuration |
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 |
2-letter ISO region code for current content region. Ex. “US” Please refers to: https://en.wikipedia.org/wiki/ISO_3166-1 |
postalCode |
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 ( |
Fields | |
---|---|
previousSubscriptionId |
Required. The previous subscription id to be replaced. This is not the full resource name, use the subscriptionId segment only. |
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 aligns with the previous subscription it upgrades or downgrades from. |
BILLING_CYCLE_SPEC_START_IMMEDIATELY |
The billing cycle of the new subscription starts immediately. |
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 ( |
Fields | |
---|---|
reason |
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. |
LineItem
Individual line item definition of a subscription.
JSON representation |
---|
{ "product": string, "description": string, "lineItemPromotionSpecs": [ { object ( |
Fields | |
---|---|
product |
Required. Product resource name that identifies one the line item The format is 'partners/{partner_id}/products/{productId}'. |
description |
Output only. Description of this line item. |
lineItemPromotionSpecs[] |
Optional. The promotions applied on the line item. It can be:
When used as input in Create or Provision API, specify its resource name only. |
state |
Output only. The state of the line item. |
lineItemFreeTrialEndTime |
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. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
recurrenceType |
Output only. The recurrence type of the line item. |
oneTimeRecurrenceDetails |
Output only. Details only set for a ONE_TIME recurrence line item. |
productPayload |
Optional. Product specific payload for this line item. |
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 |
Output only. The bundle details for the line item. Only populated if the line item corresponds to a hard bundle. |
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 |
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 ( |
Fields | |
---|---|
servicePeriod |
Output only. The service period of the ONE_TIME line item. |
ProductPayload
Specifies product specific payload.
JSON representation |
---|
{ "googleOnePayload": { object ( |
Fields | |
---|---|
googleOnePayload |
Product-specific payloads. Payload specific to Google One products. |
youtubePayload |
Payload specific to Youtube products. |
GoogleOnePayload
Payload specific to Google One products.
JSON representation |
---|
{ "campaigns": [ string ], "salesChannel": enum ( |
Fields | |
---|---|
campaigns[] |
Campaign attributed to sales of this subscription. |
salesChannel |
The type of sales channel through which the subscription was sold. |
storeId |
The identifier for the partner store where the subscription was sold. |
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 ( |
Fields | |
---|---|
partnerEligibilityIds[] |
The list of eligibility_ids which are applicable for the line item. |
accessEndTime |
Output only. The access expiration time for this line item. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
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. |
BundleDetails
The bundle details for a line item corresponding to a hard bundle.
JSON representation |
---|
{
"bundleElementDetails": [
{
object ( |
Fields | |
---|---|
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 |
Output only. Product resource name that identifies the bundle element. The format is 'partners/{partner_id}/products/{productId}'. |
userAccountLinkedTime |
Output only. The time when this product is linked to an end user. A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: |
Methods |
|
---|---|
|
Used by Google to check with reseller whether an add-on to the subscription is authorized. Note: The domain name should be replaced with the partner domain name with same path as here. |
|
Used by Google to check with reseller whether the subscription signup is authorized. Note: The domain name should be replaced with the partner domain name with same path as here. |
|
Used by partners to cancel a subscription service either immediately or by the end of the current billing cycle for their customers. |
|
Used by partners to create a subscription for their customers. |
|
Used by partners to entitle a previously provisioned subscription to the current end user. |
|
[Opt-in only] Most partners should be on auto-extend by default. |
|
Used by partners to get a subscription by id. |
|
Used by partners to provision a subscription for their customers. |
|
Revokes the pending cancellation of a subscription, which is currently in STATE_CANCEL_AT_END_OF_CYCLE state. |