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"
}
]
}
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.