Managing a subscription
If you're using Digital River's subscription service, gain a better understanding of how to manage subscriptions after the acquisition process is complete
Last updated
If you're using Digital River's subscription service, gain a better understanding of how to manage subscriptions after the acquisition process is complete
Last updated
If you're using Digital River's subscription service, you must manage the subscription after completing the acquisition checkout process. On this page, you'll find information on how to:
After the moves to accepted, you can activate a . To do this, retrieve each items[].subscriptionInfo.subscriptionId from the data.object of the with a type of order.accepted and send it as a path parameter in a .
In the body of the request, set state to active.
No other values can be sent in the body of this request. If you attempt to do so, then the following error is returned:
Use the event's data to obtain the customer's contact information and populate your renewal reminder notification. This notification (typically an email) should include the subscription's name and a description of its goods, the amount the customer will be charged, and the upcoming billing date.
The Subscription Notifications article (refer to Learning tools for access information) includes a complete list of renewal reminder requirements.
In invoice.items[].productDetails you can access the subscription's product data (such as name, description, image, and url) and pass this information to customers in the notification, informing them of what they're being billed for.
This is a reminder that your invoice.description subscription is set to renew on or after nextInvoiceDate. To ensure that your subscription continues without interruption, your creditCard.brand credit card ending in creditCard.lastFourDigits will be charged invoice.totalAmount in invoice.currency .
For digital services (such as SaaS), you might also want to include the date and time that customers activated their subscription:
You activated your subscription via our online store on stateTransitions.activated.
We noticed that your credit card ending in lastFourDigits is set to expire expirationMonth , expirationYear. This expiration date is prior to your next recurring payment on nextInvoiceDate. To avoid disruptions to your subscription, please visit your account management page and update your payment information.
To be notified of a successful billing attempt, configure a webhook to listen for the event with a type of subscription.extended.
You could handle subscription.extended by calling a function that moves the subscription in your system into a ready to fulfill state and then initiates the fulfillment process.
The event should also trigger a renewal confirmation message sent to the customer. The following is a partial list of the data you might retrieve from the event and pass in this notification:
name and image in items[].productDetails: Reminds customers what products and/or services are included in the subscription.
payment.sources[]: Contains source data that you can share with customers so they have basic information on the payment method funding the subscription.
totalAmount and totalTax: Informs customers how much they were charged and taxed. The event also contains similar amounts at the items[]-level.
To be notified of renewal problems, you can configure a webhook(s) to listen for:
We recommend handling it by informing shoppers that their subscription is at risk of cancellation, requesting a different payment method from them, and then, assuming they provide this information, updating the subscription's source.
The event's data.object contains both the subscription and the invoice.
The event most likely stems from changes to the subscription's payment source. For example, if a credit card funds a subscription, its billing address could have changed, the customer might have cancelled it, or it might have reached its credit limit.
Whatever the structure of your dunning process, we recommend you handle subscription.payment_failed by using the event's data.object to construct a billing failed notification that:
Informs customers of the failed payment capture attempt. For example:
We were unable to charge your creditCard.brand ending in creditCard.lastFourDigits.\
Provides a link to a page on your site where customers can resolve the issue. For example: To avoid disruptions to your subscription, please visit your account management page.\
Provide your contact information. For example: If you have any questions, visit our support site at <web address>, contact us at <email address>, or call <phone number>.
If customers click the link, redirect them to a page where they can provide a new payment method.
Before the next billing attempt, Digital River will void the invoice we couldn't collect and create a new one using the subscription's updated source.
We recommend you handle subscription.failed by setting the subscription status in your system to failed as well.
You should also send customers a failure notification that allows them to reactivate their subscription. If customers select this option, you'll need to take them through the acquisition process again.
For example, the notification might:
Inform customers of the failed renewal. Despite repeated attempts, we were unable to charge your designated payment method, and as a result, your subscription has been deactivated. \
Provide a link to the page on your site where customers can resolve the issue. To reactivate your subscription, please visit your account management page. \
Provide your contact information. If you have any questions, visit our support site at <web address>, contact us at <email address>, or call <phone number>.
In this section, you'll find information on:
You can use the same process to activate both trial and non-trial subscriptions. For details, refer to Activating a subscription.
Immediately following a successful activation request, we recommend that your integration use a POST /subscriptions/{id} to (1) update the subscription's planId so that it references a paid period plan and (2) for each items[], set the price or aggregatePrice equal to the post-trial period amount that customers agreed to pay during the subscription acquisition process.
You should send customers an expiration reminder before a trial converts to a paid subscription. After a successful conversion occurs, make sure you also send a conversion notification.
We recommend that you use subscription.reminder to trigger an email (or some other type of notification) to the customer. In the event's payload, currentPeriodEndDate, nextInvoiceDate, and totalAmount provide the data you need to inform customers (1) on what date their free trial is scheduled to expire, (2) when their first payment is scheduled, and (3) in what amount.
You should use subscription.extended as a trigger to notify customers that the trial has been converted into a paid subscription.
If you activated the subscription (i.e., its state is activeFree) then cancel the subscription.
If customers edit their billing information, present them with a form to enter the full name, email, and address (line 1, line 2, city, state, country, postal code) associated with the credit card.
If customers opt to edit their credit card's expiration date, use a cardexpiration element to provide them with an input field.
When customers want to change how they pay for a subscription, you can allow them to supply a new payment method.
The customer's billing information must be collected and stored first in both cases.
Build the createDropin() method's configuration object:
In options, set:
flow to managePaymentMethods
usage to subscription
showTermsOfSaleDisclosure to true
showComplianceSection to true
Since this is an account management flow, you can't use the checkout's payment session identifier to set sessionId. As a result, you must pass the billing information you collect from customers in billingAddress.
Pass the configuration object to createDropin(). If the request is successful, the onReady event contains the transaction's eligible payment methods:
Each payment method and its disclosures will appear in the window. If customers click the button without accepting these agreements and terms, Drop-in blocks the transaction from proceeding.
For more details, refer to the Drop-in payments integration guide and the Drop-in payments builder tool.
If you receive a 200 OK, notify customers that their subscription's designated payment method has been successfully updated.
If you receive a 200 OK, notify customers that their subscription's designated payment method has been successfully updated.
No other values can be passed in the body of a cancellation request. If you attempt to do so, the following error is returned:
On your site's subscription management page, include a cancellation button that, when clicked, sends this cancellation request to Digital River. When you receive a successful response, send the customer a subscription cancellation confirmation email and indicate that no future billing will occur.
A successful request results in the creation of an event with a type of subscription.deleted.
Only subscriptions whose state is draft can be deleted. If you attempt to delete a non-draft subscription, then the following error is thrown:
If you want to stop recurring payments on an activated subscription, you can cancel the subscription or deactivate its plan.
Deactivating a plan terminates all subscriptions that belong to that plan.
A successful request results in the creation of an event with a type of subscription.updated.
For details on handling subscription updates in free trials, refer to updating the subscription's price and plan in the Trial management section.
In most cases, if you make a subscription update, we recommend you notify customers (typically by email) of the change. In the email, include a link to the customer's subscription management page, and on that same page, make sure you install a cancellation button that, when clicked, sends a subscription cancellation request to Digital River.
For details, refer to the Modifying subscription payments section.
In an update subscription request, you can either pass items[].skuId or items[].productDetails.
For details, refer to Managing SKUs or Using product details.
A common use case for this operation is when upgrading or downgrading a customer's subscription service. For example, customers might want to migrate from basic to professional offerings.
Digital River's standardized autorenewal terms allow you to make price or aggregatePrice changes to any of a subscription's line items. You must, however, provide customers advance notification (typically by email) of the change, along with instructions on how to cancel the subscription if they don't agree to the price increase.
For each of a subscription's items[] , the default quantity is 1. So, unless you specify quantity when updating a line item in a subscription, its value is automatically set to 1 .
Any updates to quantity typically require the customer's consent.
You can activate a subscription any time after an state moves to accepted. For example, if you're selling a digital service subscription that requires no provisioning, you might build your integration so that the activation request is immediately submitted. In other scenarios, such as when a customer must install and initialize a device, you may decide to build a delay into the activation process.
When you activate the subscription, we search the acquisition for the primary payment source, retrieve its identifier, and assign that value to sourceId in the . We will on the and attempt to using this reusable source.
After activation, the following are populated: contractBindingUntil, nextReminderDate, currentPeriodEndDate, nextInvoiceDate, and activated.
Every subscription contains a billingAgreementId that references a billing agreement. For PSD2 and SCA compliance purposes, we continue to associate this billing agreement with the subscription throughout the .
Once the state is accepted, you should fulfill the goods and then submit the payment capture request.
Once a subscription is successfully acquired, you can use the with a type of order.accepted to trigger an acquisition confirmation notification.
On a , make sure you send a renewal reminder to customers. Your integration should also handle both successful and failed billing attempts.
Before attempting to collect a recurring payment, our subscription service determines whether the necessary preconditions are met. If they are, the service opens a and, on the subscription's, creates an event with a type of subscription.reminder.
You can configure when you receive this event by setting the plan's .
The event's data.object contains the along with an .
There are numerous ways to build your notification. However, we suggest converting any into a more human-readable form. The following are some (partial) examples of what you might add:
Additionally, we suggest you use the reminder event to determine whether the subscription's designated credit card will expire before the . If this is the case, remind customers to update their payment information and provide a link to the appropriate page on your site. For example:
The event's data.object contains the along with the used to capture. Since settlement has successfully occurred, the invoice's is paid.
orderId: Gives customers access to the identifier of the transaction's .
nextInvoiceDate: Provides customers with the date of the .
If Digital River can't create a billing because there's a problem with the saved source (in the case of credit cards, this is often an invalid expiration date), then we create an event with a type of subscription.invalid_source.
If you don't make this update during the grace period (i.e., the of the subscription’s ), then Digital River moves the subscription’s to lapsed and creates subscription.lapsed.
Since this is a terminal state, reactivating the isn't possible, so you'll likely want to discontinue customers' access to the service and provide instructions on restoring it.
An event with a type of subscription.payment_failed indicates that Digital River's failed to .
However, since the of the remains activePendingInvoice, you might still be able to collect payment.
Once you create a new or authenticate an existing source, you must associate it with the customer.
You'll also need to pass the source's identifier in the body of an .
An event with a type of subscription.failed indicates that our autorenewal service could not during the . As a result, the has become uncollectible and the has moved into a terminally state.
Once activated, a free trial subscription's transitions from draft to activeFree and the activatedFree timestamp is populated.
After you submit this request, the planId references the paid period plan. However, until elapses, the trial period plan controls the subscription's behavior.
On the , Digital River creates an whose type is subscription.reminder and whose data.object contains an in a state.
Assuming you updated the items[].price or items[].aggregatePrice, the invoice's totalAmount will be greater than zero and equal to the aggregated price of all the subscription's items[], plus taxes and fees calculated by Digital River.
This totalAmount is how much customers will be charged for the subscriptions , which (if you configured your trial period plan correctly) should be the same as the . In other words, customers won't be charged until the free trial period is over.
On the , Digital River moves the to and the to and then attempts to collect payment for the number of days specified by the trial period plan's collectionPeriodDays.
If any of these collection attempts are successful, Digital River marks the invoice as and the as , populates the activated timestamp and creates an whose type is subscription.extended.
If payment capture fails, the becomes , and the moves into a state. To learn more, refer to Handling failed renewals.
Customers may cancel their during its trial period to avoid getting charged. In these cases, you have two options:
If the subscription's is draft (i.e., you haven't activated it yet), you should delete the subscription.
Sometimes, you might want to extend a customer's free trial period or keep customers at a no-charge level indefinitely. To do this, after you activate the subscription, do not update its price. By not performing this operation, a items[] will have a price or aggregatePrice of 0.0on the nextInvoiceDate, and, as a result, Digital River doesn't make any invoice collection attempts, and the subscription's state remains activeFree.
You can also push an subscription back into an state. Offering various subscription pricing tiers is useful, and customers can ask to downgrade their access to the basic or free level.
To do this, send a request that updates the price or aggregatePrice of each of the subscription's items[] to 0.0 and the planId to an appropriate . On the , the subscription's reverts to activeFree.
When customers want to manage their subscriptions, you can associated with their record:
For each subscription, access its payment by passing sourceId in a request.
To modify a payment , its must be active, activeFree, or activePendingInvoice. If you meet this precondition, you can:
If a sourceId references a with a type of creditCard, you can provide customers with the ability to update that card's billing information or expiration date.
If you want to display the card's current billing information and card information to customers, you can retrieve that data from the owner and creditCard blocks.
Once customers enter and save their changes, pass the submitted data to updateSource(). Make sure you configure the appropriate version of the method, depending on whether customers submit updated (a) billing address information, (b) card expiration information, or (c) both. In both versions, you need to add the id and clientSecret to the method's configuration object.
How you replace a current with a new source depends on whether you're using Drop-in payments or DigitalRiver.js with Elements.
If customers accept the terms, submit their information, and the resulting create source request is successful, the onSuccess event contains a that is readyForStorage and chargeable.
Set currency to the same value as the currency
If the create source request is successful, the response contains a that is readyForStorage and chargeable.
Send the , , and identifiers to your backend.
Use a to attach the source to the customer. It flips the source's reusable attribute to true.
To update the subscription, send its identifier as a path parameter in a . In the body of the request, specify the new sourceId.
When customers want to change how they pay for a subscription, you can give them the option of selecting one of their saved payment .
To access these sources, send the identifier in a request. From the response, you can retrieve any of the sources[], since, by default, they're all chargeable and reusable.
Use a selection control to display these saved sources to customers. With credit cards, you can retrieve brand, expirationMonth, expirationYear, and lastFourDigits and display this information to customers so they can identify the card. If the customer uses a saved , retrieve its unique identifier.
To update the subscription, send its identifier as a path parameter in a and, in the request body, specify the selected sourceId.
When you either (1) receive a request from the customer to cancel a subscription, and the request adheres to the terms of the agreement (or you grant the customer a waiver), or (2) you decide to cancel the subscription, send a with state set to cancelled in the request's payload.
Only active , activeFree, and activePendingInvoice subscriptions can be cancelled. When you cancel an subscription, the underlying invoice is moved into a state.
A successful cancellation request returns a 200 OK, moves the subscription into a state and prevents billing from occurring on the .
To delete a subscription, retrieve its unique identifier, and pass it as a path parameter in a request.
changes the behavior of all the it controls. As a result, we generally recommend only using the POST /plans/{planId} operation to optimize or phase it out.
For details on how changing a state affects a , refer to .
To stop renewal reminders from getting generated on a , you need to by assigning a negative integer to .
When a on that moves into its next billing period, Digital River deletes its . As a result, the with a type of subscription.reminder does not get created.
If you make this update to a reminderOffSetDays, then the billing behavior of all of its remains unchanged.
A request allows you to both activate a subscription and cancel a subscription as well as make updates to any of its following attributes:
To successfully update a , its must be draft, active, activeFree, or activePendingInvoice.
When Digital River opens an invoice on , we move the subscription's state to activePendingInvoice and implement a blackout period. As a result, any updates you make to the subscription during this period won't take effect until the next billing cycle.
Therefore, performing a or can't be used to identify a subscription's current state. Instead, these requests return the scheduled settings for the next renewal.
If you want to modify the timing of a subscription's renewal reminder event, when billing is initiated, or the length of the payment collection period, you must associate the subscription with a different planId. If you move an active subscription to a different , the new settings are applied to future billing periods.
Always acquire the customer's consent before changing a subscription's billing frequency. In most cases, we recommend you create a new subscription. Since billing frequency is defined by a plan's , and these attributes can't be modified in a , you'd need to associate the subscription with a different plan, which can potentially cause issues.
For example, you might have a subscription on an annually renewing plan. If you use a to associate the subscription with a different, monthly-billing plan, then the subscription will remain on its current annual plan until the end of the . Not until that point will the subscription switch to the monthly plan.
When any of your webhook endpoints receive an whose type is order.chargeback, parse its payload to determine whether the contains a subscriptionId. If it does, you should cancel the subscription to avoid further chargebacks and fees.
