Upgrade and Downgrade Flows
Stay organized with collections
Save and categorize content based on your preferences.
Payments Reseller Subscription API reuses Create/Provision APIs to upgrade/downgrade an existing subscription. The choice of which API to use depends on how you manage the user sign up.
Google Managed User Signup
- partners.subscriptions.provision API can upgrade, downgrade a subscription regardless of its entitlement status. If an existing subscription is already activated by a Google user, the newly provisioned subscription will carry over their google account for the new plan.
Partner Managed User Signup (based on oauth consent)
You may need to additionally consider some common error scenarios when you use oauth consent:
User revoked oauth permission after initial consent, and requested upgrade.
This will affect partners who use oauth refresh tokens. See token expiration for detailed scenarios when a refresh token might no longer work.
- If the partner must complete the transaction in their own system first before calling Google Reseller APIs, a final fix would require the user to grant oauth permission. Partner can consider encouraging the user to provide consent again. If the above step fails after a certain period of time. Partner could:
- reverse the transaction of upgrade/downgrade in their system.
- or cancel the initial subscription with Google, and call Provision to create the new subscription without specifying upgrade_downgrade_details.
- Partners could also avoid inconsistencies between their system and Google by always starting upgrade/downgrade with Reseller API first. And only update the partner's own system after the Create() API is successful.
User mismatch On Create
This means the user switched to a different gmail than the previous subscription. Create API returns error code ERROR_CODE_SUBSCRIPTION_USER_MISMATCH. Partner should navigate the user to restart the oauth consent flow with their previously entitled gmail account.
If the partner uses oauth refresh tokens, this would not be possible. New access token will always be the same user who initially granted permission.
User mismatch On Provision
The end user may have initiated entitle(), and Google successfully granted entitlement. However, the response failed to reach back to the partner. Then the partner's system may register the subscription as not activated. If the partner calls Provision again, they could get ERROR_CODE_SUBSCRIPTION_USER_MISMATCH. In this case, the partner should use Create() instead.
If a refresh token is available from previous user consent, it can be reused for Create.
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 2024-08-21 UTC.
[null,null,["Last updated 2024-08-21 UTC."],[[["\u003cp\u003eThe Payments Reseller Subscription API utilizes Create/Provision APIs for subscription upgrades and downgrades, with API selection contingent on user signup management.\u003c/p\u003e\n"],["\u003cp\u003eGoogle-managed signups allow using the Provision API for upgrades/downgrades regardless of entitlement, transferring existing Google accounts to the new plan.\u003c/p\u003e\n"],["\u003cp\u003ePartner-managed signups (OAuth-based) offer flexibility: Provision API for inactive subscriptions, and Create API for activated subscriptions by the same user.\u003c/p\u003e\n"],["\u003cp\u003eOAuth consent scenarios introduce potential error handling, requiring strategies for revoked permissions and user mismatches during upgrades/downgrades.\u003c/p\u003e\n"],["\u003cp\u003eAddressing OAuth consent errors may involve re-consent, transaction reversals, or prioritizing Reseller API calls before updating partner systems.\u003c/p\u003e\n"]]],["The Payments Reseller Subscription API uses `provision` and `create` APIs for subscription upgrades/downgrades. For Google-managed signups, `provision` handles all upgrades/downgrades, carrying over the user's Google account. For partner-managed signups, `provision` is used if the user hasn't activated the subscription, and `create` is used if the user already has. Common errors include revoked OAuth permissions and user mismatches, which may necessitate re-consent, transaction reversal, or using the `create` API instead. Inconsistency between partner's system and Google can be avoided by calling Reseller API before updating the partner's system.\n"],null,["# Upgrade and Downgrade Flows\n\nPayments Reseller Subscription API reuses Create/Provision APIs to upgrade/downgrade an existing subscription. The choice of which API to use depends on how you manage the user sign up.\n\nGoogle Managed User Signup\n--------------------------\n\n- [partners.subscriptions.provision](/payments/reseller/subscription/reference/rest/v1/partners.subscriptions/provision) API can upgrade, downgrade a subscription regardless of its entitlement status. If an existing subscription is already activated by a Google user, the newly provisioned subscription will carry over their google account for the new plan.\n\nPartner Managed User Signup (based on oauth consent)\n----------------------------------------------------\n\n- [partners.subscriptions.provision](/payments/reseller/subscription/reference/rest/v1/partners.subscriptions/provision) API can upgrade, downgrade a subscription if the user has not activated the existing subscription.\n\n- [partners.subscriptions.create](/payments/reseller/subscription/reference/rest/v1/partners.subscriptions/create) API can upgrade, downgrade a subscription for the same user who has already activated the existing subscription.\n\nYou may need to additionally consider some common error scenarios when you use oauth consent:\n\n#### User revoked oauth permission after initial consent, and requested upgrade.\n\nThis will affect partners who use oauth refresh tokens. See [token expiration](https://developers.google.com/identity/protocols/oauth2#expiration) for detailed scenarios when a refresh token might no longer work.\n\n- If the partner must complete the transaction in their own system first before calling Google Reseller APIs, a final fix would require the user to grant oauth permission. Partner can consider encouraging the user to provide consent again. If the above step fails after a certain period of time. Partner could:\n - reverse the transaction of upgrade/downgrade in their system.\n - or cancel the initial subscription with Google, and call Provision to create the new subscription without specifying upgrade_downgrade_details.\n- Partners could also avoid inconsistencies between their system and Google by always starting upgrade/downgrade with Reseller API first. And only update the partner's own system after the Create() API is successful.\n\n#### User mismatch On Create\n\nThis means the user switched to a different gmail than the previous subscription. Create API returns error code `ERROR_CODE_SUBSCRIPTION_USER_MISMATCH`. Partner should navigate the user to restart the oauth consent flow with their previously entitled gmail account.\n\nIf the partner uses oauth refresh tokens, this would not be possible. New access token will always be the same user who initially granted permission.\n\n#### User mismatch On Provision\n\nThe end user may have initiated entitle(), and Google successfully granted entitlement. However, the response failed to reach back to the partner. Then the partner's system may register the subscription as not activated. If the partner calls Provision again, they could get `ERROR_CODE_SUBSCRIPTION_USER_MISMATCH`. In this case, the partner should use Create() instead.\n\nIf a refresh token is available from previous user consent, it can be reused for Create."]]