Replace a Subscription

Introduction

The subscription replacement feature allows merchants to seamlessly transition a customer's subscription to another product without the need to cancel the existing subscription and create a new one. This feature is designed to simplify the process for merchants while ensuring transparency and efficiency in managing subscription changes.

You can replace a subscription by initiating replacement request, the new SubscriptionID is in the request and old subscriptionID is sent in the endpoint.

API Endpoint:

/v1/clients/{clientId}/subscriptions/{subscriptionId}/replacement

Request

{
    "newSubscriptionId": string,
    "subscriptionProductId": string,
    "billingDayOffset": short,
    "activation": {
      "type": enum,
      "date?": datetime
    }
    "metadata": [
    {
      "key": string,
      "value": string
    }
}

Response

{
    "newSubscriptionId": string,
    "oldSubscriptionId": string,
    "isCompleted": bool,
    "status": enum,
    "createdAt": dateTime,
    "updatedAt": dateTime,
    "activationDate": dateTime,
    "metadata": [
    {
      "key": string,
      "value": string
    }
    "_links": string
}

Endpoint Criteria

• Replacement Limitation: Only one replacement can exist for each subscription ID.
• Original Subscription Status: The original subscription must have a status of "Active".
• Replacement Completion: Replacement is considered complete once the activation date matches the current date.

Invoicing Criteria

Invoicing associated with the replacement process includes:

• Refund for Remaining Days: Refund for any remaining days of the current subscription period if replacement occurs mid-period.
• First Invoice of New Subscription: Inclusion of the first invoice for the new subscription product.
• Partial Period: Inclusion of charges or adjustments for any partial period if replacement occurs mid-period.
• Timing: Invoicing follows the schedule of the new subscription.

Value Generation

The subscription replacement feature offers the following benefits to merchants:

• Functionality: Essential functionality for efficiently managing subscription changes.
• Customer Retention and Satisfaction: Facilitates seamless transitions, leading to higher customer satisfaction.
• Transparency: Provides transparency in invoice generation and settlements.