Critical User Journeys
Stay organized with collections
Save and categorize content based on your preferences.
Starting Subscription
- There are two ways for partners to start a subscription on behalf of their customer. Both ways require an authorization by the end user using OAuth 2.0 and they differ on how Google will charge the partner.
- Create: Create a subscription for the user. The created subscription is associated with the end user inferred from the end user credentials.
- Provision and Entitle: First provision a subscription for the user without a Google account. Follow up by Entitle on a provisioned subscription which is associated with the end user inferred from the end user credentials.
- Billing cycle : the billing cycle starts upon Create (activation of subscription) or Provision (purchase of subscription)
- User Authorized Requests : Starting Subscription (Create or Entitle) requires User Authorization by an authenticated User. Google uses OAuth 2.0 to authorize requests.
Grace Period
If grace period is enabled for the product, subscriptions enter grace period at the end of billing cycle if it’s not authorized by partner for charge (or) not manually extended.
During this grace period, users won't lose access to your current subscription plan and continue to use the Google service.
Manual Extend
When subscription has not been extended and the current billing cycle ends, subscriptions can be put into a grace period.
- Extending the subscription during the grace period will put the subscription back to active status.
- If subscription is not extended during the grace period, it will automatically get canceled at the end of the grace period.
Outbound Authorization
In the event the partner rejects authorizeCharge during recurrence, subscription will be moved to grace period.
- Google would attempt to retry authorizeCharge every 24 hours until the grace period ends.
- If the partner approves a retry attempt of authorizeCharge during the grace period, the subscription moves back to the active state.
- If the partner rejects all the retry attempts of authorizeCharge, the subscription will get canceled at the end of the grace period.
Modifying Subscription
- Upgrade/Downgrade : At any time during the subscription, partner can upgrade or downgrade to a new Google service plan using Create or Provision (API Guide)
- Modifying subscriptions requires User Authorization and the request must include an authorization token
- Billing Adjustments : There are 2 options to handle billing cycle (BillingCycleSpec) when modifying the subscription and both will initiate a prorated refund based on the remaining days on the current billing cycle
- Start a new billing cycle with a full charge on the new subscription.
- Align with the previous subscription with a prorated charge on the first month of the new subscription.
Add-ons to existing Subscription
- Currently, you can only purchase add-ons to subscriptions on Google's surface.
- If the partner is opted into outbound authorization
- A synchronous outbound auth will be issued to partners to authorize the purchase of add-on. The end user will see an error in the purchase flow if the request is not authorized.
- Once the partner authorizes the purchase of add-on google will issue another asynchronous outbound auth before proceeding for a prorated charge, this can happen immediately after authorize add-on call or when the add-on free trial ends if applicable. The addon will be deactivated if the authorize charge is not rejected. Google will retry until a valid response is received.
- The first charge for the add-on will be prorated to align with the billing cycle of the base subscription. After that, all subscription line items will be billed together.
- Partners can listen to the Pub/Sub notification from Google for such events and take appropriate action to reflect the change in their own systems.
Canceling Subscription
- Regular Cancelation (cancel): The subscription is canceled at the end of the billing cycle and the consumer retains their subscription until the end of the billing cycle. There are no refunds or grace periods for the subscription.
- Immediate Cancelation: The subscription is canceled immediately
- UndoCancel : Used by partners to revoke the pending cancellation of a subscription, which is currently in STATE_CANCEL_AT_END_OF_CYCLE state
- Once subscription is canceled, it can not be reinstated to an active subscription.
Canceling from Google
- There are few cases where users can remove a Google service. e.g. Delete Google Account, Delete a Google subscription.
- Partners must listen to the Pub/Sub notification from Google for such events and take appropriate action (e.g: Remove Google One service and notify customers. Stop billing).
Verify Subscription
- Partners are able to verify the status of the subscriptions via using the get API to help troubleshoot technical issues.
- Subject to the commercial alignments, partners can offer promotions (e.g. Free trial, Introductory pricing) when creating a new subscription for the users.
- Google may check for eligibility on the account level, both Google Account and Partner User Token (identifier of the end-user in partner's system).
- To find the eligible promotions or evaluate eligibility of a user's Google account, partner can use FindEligible with User Authorized Requests.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-03-05 UTC.
[null,null,["Last updated 2025-03-05 UTC."],[[["\u003cp\u003ePartners can start Google subscriptions for customers using two methods, both requiring end-user authorization via OAuth 2.0, with variations in billing.\u003c/p\u003e\n"],["\u003cp\u003eSubscriptions enter a grace period if not authorized for charge at the end of the billing cycle, allowing users continued access while partners can extend or cancel.\u003c/p\u003e\n"],["\u003cp\u003ePartners can modify existing subscriptions through upgrades/downgrades, requiring user authorization and potentially leading to billing adjustments.\u003c/p\u003e\n"],["\u003cp\u003eAdd-ons are currently purchased on Google's platform and trigger outbound authorization requests for partners, followed by prorated charges aligned with the base subscription.\u003c/p\u003e\n"],["\u003cp\u003ePartners can cancel subscriptions regularly or immediately, with options to undo pending cancellations, while Google-initiated cancellations are communicated via Pub/Sub notifications.\u003c/p\u003e\n"],["\u003cp\u003eSubscription verification and promotion options are available to partners, with Google managing eligibility checks and potential user-level restrictions.\u003c/p\u003e\n"]]],["Partners can start subscriptions via \"Create\" or \"Provision/Entitle,\" both requiring user authorization via OAuth 2.0. Subscriptions enter a grace period if charges aren't authorized, allowing continued service. During grace periods, manual extension is possible; otherwise, subscriptions are canceled. Partners can upgrade/downgrade plans and adjust billing. Add-ons are purchased on Google's surface with prorated charges. Subscriptions can be canceled regularly or immediately, and pending cancellations can be undone. Promotions, including free trials, are available, and partners can verify eligibility. Google offers Pub/Sub notifications for subscription changes.\n"],null,["# Critical User Journeys\n\n### Starting Subscription\n\n- There are two ways for partners to start a subscription on behalf of their customer. Both ways require an authorization by the end user using OAuth 2.0 and they differ on how Google will charge the partner.\n - [Create](https://developers.google.com/payments/reseller/subscription/reference/rest/v1/partners.subscriptions/create): Create a subscription for the user. The created subscription is associated with the end user inferred from the end user credentials.\n - [Provision](https://developers.google.com/payments/reseller/subscription/reference/rest/v1/partners.subscriptions/provision) and [Entitle](https://developers.google.com/payments/reseller/subscription/reference/rest/v1/partners.subscriptions/entitle): First provision a subscription for the user without a Google account. Follow up by Entitle on a provisioned subscription which is associated with the end user inferred from the end user credentials.\n - Billing cycle : the billing cycle starts upon Create (activation of subscription) or Provision (purchase of subscription)\n- [User Authorized Requests](https://developers.google.com/payments/reseller/subscription/reference/index/User.Authorized.Requests) : Starting Subscription (Create or Entitle) requires User Authorization by an authenticated User. Google uses [OAuth 2.0](https://developers.google.com/identity/protocols/oauth2) to authorize requests.\n\n#### Grace Period\n\nIf grace period is enabled for the product, subscriptions enter grace period at the end of billing cycle if it's not authorized by partner for charge (or) not manually extended.\n\nDuring this grace period, users won't lose access to your current subscription plan and continue to use the Google service.\n\n##### Manual Extend\n\nWhen subscription has not been extended and the current billing cycle ends, subscriptions can be put into a grace period.\n\n- Extending the subscription during the grace period will put the subscription back to active status.\n- If subscription is not extended during the grace period, it will automatically get canceled at the end of the grace period.\n\n##### Outbound Authorization\n\nIn the event the partner rejects [authorizeCharge](https://developers.google.com/payments/reseller/subscription/reference/rest/v1/partners.purchaseorders/authorizeCharge) during recurrence, subscription will be moved to grace period.\n\n- Google would attempt to retry authorizeCharge every 24 hours until the grace period ends.\n- If the partner approves a retry attempt of authorizeCharge during the grace period, the subscription moves back to the active state.\n- If the partner rejects all the retry attempts of authorizeCharge, the subscription will get canceled at the end of the grace period.\n\n### Modifying Subscription\n\n- Upgrade/Downgrade : At any time during the subscription, partner can upgrade or downgrade to a new Google service plan using Create or Provision ([API Guide](https://developers.google.com/payments/reseller/subscription/reference/Onboarding/Upgrade.and.Downgrade.Flows))\n- Modifying subscriptions requires User Authorization and the request must include an authorization token\n- Billing Adjustments : There are 2 options to handle billing cycle ([BillingCycleSpec](https://developers.google.com/payments/reseller/subscription/reference/rest/v1/partners.subscriptions#billingcyclespec)) when modifying the subscription and both will initiate a prorated refund based on the remaining days on the current billing cycle\n - Start a new billing cycle with a full charge on the new subscription.\n - Align with the previous subscription with a prorated charge on the first month of the new subscription.\n\n#### Add-ons to existing Subscription\n\n- Currently, you can only purchase add-ons to subscriptions on Google's surface.\n- If the partner is opted into outbound authorization\n - A synchronous outbound auth will be issued to partners to [authorize the purchase of add-on](https://developers.google.com/payments/reseller/subscription/reference/index/Outbound.authorizations.(optional)#in-app-subscription-add-on-purchase). The end user will see an error in the purchase flow if the request is not authorized.\n - Once the partner authorizes the purchase of add-on google will issue another asynchronous outbound auth before proceeding for a [prorated charge](https://developers.google.com/payments/reseller/subscription/reference/rest/v1/partners.purchaseorders/authorizeCharge), this can happen immediately after authorize add-on call or when the add-on free trial ends if applicable. The addon will be deactivated if the authorize charge is not rejected. Google will retry until a valid response is received.\n- The first charge for the add-on will be prorated to align with the billing cycle of the base subscription. After that, all subscription line items will be billed together.\n- Partners can listen to the [Pub/Sub notification](https://developers.google.com/payments/reseller/subscription/reference/index/Receive.Notifications) from Google for such events and take appropriate action to reflect the change in their own systems.\n\n### Canceling Subscription\n\n- Regular Cancelation ([cancel](https://developers.google.com/payments/reseller/subscription/reference/rest/v1/partners.subscriptions/cancel)): The subscription is canceled at the end of the billing cycle and the consumer retains their subscription until the end of the billing cycle. There are no refunds or grace periods for the subscription.\n- Immediate Cancelation: The subscription is canceled immediately\n- [UndoCancel](https://developers.google.com/payments/reseller/subscription/reference/rest/v1/partners.subscriptions/undoCancel) : Used by partners to revoke the pending cancellation of a subscription, which is currently in STATE_CANCEL_AT_END_OF_CYCLE state\n- Once subscription is canceled, it can not be reinstated to an active subscription.\n\n#### Canceling from Google\n\n- There are few cases where users can remove a Google service. e.g. Delete Google Account, Delete a Google subscription.\n- Partners must listen to the Pub/Sub notification from Google for such events and take appropriate action (e.g: Remove Google One service and notify customers. Stop billing).\n\n### Verify Subscription\n\n- Partners are able to verify the status of the subscriptions via using the [get](https://developers.google.com/payments/reseller/subscription/reference/rest/v1/partners.subscriptions/get) API to help troubleshoot technical issues.\n\n### Using Promotions\n\n- Subject to the commercial alignments, partners can offer promotions (e.g. Free trial, Introductory pricing) when creating a new subscription for the users.\n- Google may check for eligibility on the account level, both Google Account and Partner User Token (identifier of the end-user in partner's system).\n- To find the eligible promotions or evaluate eligibility of a user's Google account, partner can use [FindEligible](https://developers.google.com/payments/reseller/subscription/reference/rest/v1/partners.promotions/findEligible) with [User Authorized Requests](https://developers.google.com/payments/reseller/subscription/reference/index/User.Authorized.Requests)."]]