Payments Reseller Subscription API today reuses Create/Provision APIs to support the upgrade/downgrade of an existing subscription. There are multiple possible API flows.
Happy Paths
Provision -> Provision
Partner provisions a subscription in the initial transaction, and before the user activates the service (using entitle), partner can allow them to upgrade/downgrade without granting oauth consent.
Create -> Create
Partner asks user to grant oauth permission in the initial transaction, and calls Create() API again to upgrade/downgrade later. The second Create can either:
- ask the user to grant oauth consent again, or
- reuse a previously stored refresh token to acquire new access token.
Provision -> Entitle -> Create
Partner provisions a subscription in the initial transaction, then partner asks that the user activates the service (using entitle) first before they can upgrade/downgrade. After successful service activation, partner can then either:
- ask the user to grant oauth consent again, or
- reuse a previously stored refresh token to acquire new access token.
Provision -> Create
Partner provisions a subscription in the initial transaction, and before the user activates the service (using entitle), partner allows the user to upgrade/downgrade with an initial oauth consent.
Not Allowed
- Create -> Provision
- Provision -> Entitle -> Provision
We don't allow removing an entitled user during upgrade/downgrade.
Handling Error Scenarios
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.
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.