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

• ClientID = Your assigned Riverty client-id
• SubscriptionID = Your internal subscription identifier to this subscription

Request

{
  "newSubscriptionId": "new-subscription-id",
  "subscriptionProductId": "new-product-id",
  "billingDayOffset": 10,
  "activation": {
    "type": "AFTER_CURRENT_PERIOD"
  },
  "metadata": [
    {
      "key": "order-id",
      "value": "9a1a03f5-dbb0-4e32-9fc2-89c9be29780a"
    }
  ]
}

Response

{
  "subscriptionId": "new-subscription-id3",
  "oldSubscriptionId": "old-subscription-id2",
  "subscriptionProductId": "new-product-id",
  "billingDayOffset": 10,
  "activation": {
    "type": "AFTER_CURRENT_PERIOD",
    "date": "2023-03-01"
  },
  "status": "PENDING",
  "createdAt": "2023-02-01",
  "updatedAt": "2023-02-14",
  "activationDate": "2023-03-01",
  "metadata": [
    {
      "key": "order-id",
      "value": "9a1a03f5-dbb0-4e32-9fc2-89c9be29780a"
    }
  ]
}

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.

Activation Types

• INSTANT: Immediately close the old subscription and activate the new subscription instantly.
• AFTER_CURRENT_PERIOD: Activate the new subscription after the current period of the old one is complete

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.