User-facing APIs for subscription upgrades, downgrades, and renewal adjustments

With Arc XP Subscriptions, you can update and downgrade paid subscriptions in either of the following three ways:

• With customer support agents through the customer support portal.
• With user-facing, public APIs for your site.
• With server-to-server, developer APIs for bulk subscription changes.

This document describes the public API endpoints that enable clients to build workflows for paid subscription upgrades and downgrades with Braintree and Stripe Intents payment gateways.

Why use public APIs for active subscription updates

With public API endpoints, you can upgrade and downgrade paid subscriptions in the following cases:

• To retain a customer:
  • A customer switches from a yearly to a monthly payment for the same product.
  • A customer pays a reduced price for the same product.
  • A customer downgrades to a new product at the end of the term.
    For example, they go from a premium to a basic subscription at the end of the payment period.
• To provide higher value: A customer upgrades to a new product now.
  For example, they go from a basic to a premium subscription now.
• To ensure longer commitment: A customer goes from a monthly subscription to a yearly one.

Public API endpoints provide multiple options for charging and refunding without risking refund errors or customer loss. They mimic the upgrades and downgrades that CSR admins can perform in the Admin tool, with one exception: Only customer support representatives can give free upgrades to customers.
To learn more about the cases Arc XP does and does not support, see Supported use cases.

important

The API endpoints in this document do not support upgrades and downgrades for payment gateways other than Braintree or Stripe Intents.

How using public API endpoints benefits your business

New public APIs enable you to build upgrade and downgrade workflows that support key business strategies, including:

• Retaining customers: Offering lower-priced subscriptions before cancellation.
• Encouraging longer commitments: Transitioning users to longer renewal periods.
• Driving higher-value conversions: Promoting feature-rich subscription tiers.

Public API endpoints for upgrade and downgrade

You can enable paid subscription upgrades and downgrades for users paying through Braintree and Stripe Intents with the following public API endpoints:

• POST Initialize an upgrade/downgrade: POST /sales/public/v1/subscription/upgradedowngrade
• PUT Finalize an upgrade/downgrade: PUT /sales/public/v1/subscription/upgradedowngrade

To learn about public API endpoints in detail, navigate to the Subscriptions APIs document.

Prerequisites

Ensure you have the following to enable subscription upgrade and downgrade with public API endpoints:

• Configured product SKU, priceCode, and reasonCode (optional) for the upgrade and downgrade in the Subscription Product Retail admin.
• Developed front-end applications that do the following:
  • Enable your customers to learn about the upgrade and downgrade options.
    For example, a prompt to request an upgrade or a downgrade on a webpage with a description of options.
  • Retain the customers who plan to downgrade or cancel.

The following sections describe how the public APIs work and the related flow in two steps.

Step 1. POST Initialize and upgrade/downgrade

The initialization process works as follows:

1. A customer decides to upgrade or downgrade a paid subscription based on the front-end application offer.

2. The customer’s browser calls the POST Initialize an upgrade/downgrade endpoint.

3. The POST Initialize an upgrade/downgrade endpoint generates the following:

   • A proposal for the customer to see the change they are about to make to their subscription: An upgrade or a downgrade.
   • A sessionId to pass to the Finalize an upgrade/downgrade endpoint as a required parameter.

   important

   The customer has 10 minutes to decide if they accept the proposal. If they call the Initialize an upgrade/downgrade endpoint after 10 minutes, the system shows the sessionID as invalid.
   To learn more about error statuses and codes for this endpoint, see Subscriptions APIs.

4. The user accepts the upgrade or downgrade terms.

Step 2. PUT Finalize an upgrade/downgrade

The finalization process works as follows:

1. The front-end application passes the following to the PUT Finalize an upgrade/downgrade endpoint to finalize the proposal:
   • sessionID
   • reasonCode: If configured.
2. The endpoint attempts to finalize the upgrade or downgrade and generates the response.
   To learn about the response codes, see the PUT Finalize an upgrade/downgrade endpoint in Subscriptions APIs.
3. The endpoint attempts the full charge if the upgrade or downgrade requires it.
4. If the charge is successful, the endpoint responds with the following message: 200 The requested upgrade/downgrade was successful.
5. The endpoint attempts a prorated refund if the upgrade or downgrade requires it.
6. If the refund fails, the endpoint triggers a failed refund WebSocket event.

Note

You can develop a flow to notify your customers about a failed refund with the failed refund WebSocket event. For example, you can connect it to your email service provider. Then, if your customer receives a Failed Refund email notification, they can contact your customer support to get a refund.

Subscription update flow example

The following figure exemplifies a flow in which a user decides to change from a yearly to a monthly subscription. Click to enlarge the image.

Figure 1. Subscription upgrade flow

Supported use cases

See the following table to learn about four cases when you can use public API endpoints to upgrade and downgrade paid subscriptions.

Input			Output			Use case example
SKU	Time SKU changes	Current term	Prorated refund	Full charge	Product
Does not change	N/A	Ends	Yes	Yes	Does not change	From annual to monthly payment
Does not change	N/A	Continues	No	No	Does not change	Reduced price for the same product
Changes	Now	Ends	Yes	Yes	Changes	Product upgrade now
Changes	End of the current term	Continues	No	No	Scheduled to be changed at the end of the current term	Product downgrade at the end of the term

Table 1. Use cases that API endpoints support

important

The use cases are not limited to examples listed in the Use case example column. Ensure to review the Input and the Output columns to decide on the best use case for your customers.

Unsupported use cases

See the following table to learn about four cases when you cannot use public API endpoints to upgrade and downgrade paid subscriptions.

Input			Output			Use case example
SKU	Time SKU changes	Current term	Prorated refund	Full charge	Product
Changes	Now	Continues	N/A	N/A	N/A	Free upgrade for the remainder of the term. Note: While not available through APIs, can be done through CSR
Changes	End of the current term	Ends	N/A	N/A	N/A	Product upgraded at the end of the current term

Table 2. Use cases that API endpoints do not support