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 , 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 of the with a of 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:
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.
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.
name and image in items[].productDetails: Reminds customers what products and/or services are included in the subscription.
totalAmount and totalTax: Informs customers how much they were charged and taxed. The event also contains similar amounts at the items[]-level.
Informs customers of the failed payment capture attempt. For example:
We were unable to charge your creditCard.brand ending in creditCard.lastFourDigits.\
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.
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 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:
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.
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.
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.
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:
Only subscriptions whose state is draft can be deleted. If you attempt to delete a non-draft subscription, then the following error is thrown:
Deactivating a plan terminates all subscriptions that belong to that plan.
In an update subscription request, you can either pass items[].skuId or items[].productDetails.
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 , 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 . For compliance purposes, we continue to associate this billing agreement with the subscription throughout the .
Once the state is , you should fulfill the goods and then .
Once a subscription is successfully acquired, you can use the with a of to trigger an .
On a , make sure you . Your integration should also handle both and 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 with a of .
You can configure when you receive this event by setting the plan's .
The event's contains the along with an .
Use the event's data to obtain the customer's contact information and populate your . 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 article (refer to for access information) includes a complete list of renewal reminder requirements.
For details, refer to .
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:
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 and update your payment information.
To be notified of a successful billing attempt, to listen for the with a of .
The event's contains the along with the used to capture. Since settlement has successfully occurred, the invoice's is paid.
The event should also trigger a sent to the customer. The following is a partial list of the data you might retrieve from the event and pass in this notification:
orderId: Gives customers access to the identifier of the transaction's .
nextInvoiceDate: Provides customers with the date of the .
payment.sources[]: Contains data that you can share with customers so they have basic information on the payment method funding the subscription.
The article (refer to for access information) provides a comprehensive list of the information you must include in the renewal notification.
To be notified of renewal problems, you can to listen for:
If Digital River can't create a billing because there's a problem with the saved (in the case of credit cards, this is often an invalid expiration date), then we create an with a of .
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, .
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 .
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 with a of indicates that Digital River's failed to .
The event's contains both the subscription and the invoice.
The most likely stems from changes to the subscription's . For example, if a funds a subscription, its billing address could have changed, the customer might have cancelled it, or it might have reached its credit limit.
However, since the of the remains activePendingInvoice, you might still be able to collect payment.
Whatever the structure of your , we recommend you handle by using the event's data.object to construct a that:
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 .\
For details, refer to on the page.
Once you create a new or , you must .
You'll also need to pass the source's identifier in the body of an .
An with a of indicates that our autorenewal service could not during the . As a result, the has become uncollectible and the has moved into a terminally state.
We recommend you handle by setting the subscription status in your system to failed as well.
You should also that allows them to reactivate their subscription. If customers select this option, you'll need to take them through the acquisition process again.
Provide a link to the page on your site where customers can resolve the issue. To reactivate your subscription, please visit your . \
You can use the same process to activate both trial and non-trial subscriptions. For details, refer to .
Once activated, a free trial subscription's transitions from draft to activeFree and the activatedFree timestamp is populated.
Immediately following a successful , we recommend that your integration use a POST /subscriptions/{id} to (1) update the subscription's planId so that it references a 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.
After you submit this request, the planId references the . However, until elapses, the trial period plan controls the subscription's behavior.
On the , Digital River creates an whose is and whose 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 correctly) should be the same as the . In other words, customers won't be charged until the free trial period is over.
You should before a trial converts to a paid subscription. After a successful conversion occurs, make sure you also .
We recommend that you use 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.
On the , Digital River moves the to and the to and then attempts to collect payment for the number of days specified by the 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 is .
You should use subscription.extended as a trigger to .
If payment capture fails, the becomes , and the moves into a state. To learn more, refer to .
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 .
If you (i.e., its state is activeFree) then .
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 , 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.
For more details on how to modify subscriptions, refer to .
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.
If customers opt to edit their credit card's expiration date, use a to provide them with an input field.
Once customers enter and save their changes, pass the submitted data to . 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 or .
Build the createDropin() method's :
In , set:
to managePaymentMethods
to subscription
to true
to true
Since this is an , you can't use the checkout's to set sessionId. As a result, you must pass the billing information you collect from customers in .
Pass the configuration object to . If the request is successful, the event contains the transaction's eligible payment methods:
If customers accept the terms, submit their information, and the resulting create source request is successful, the event contains a that is and .
For more details, refer to the and the .
Configure using the following filters:
Set currency to the same value as the currency
to collect the customer's sensitive payment information.
When customers submit their information, configure and call the method:
Set to subscription and futureUse to true
Since this is an , you can't provide a checkout's . As a result, you must pass the billing information you collect from customers in billingAddress.
If the create source request is successful, the response contains a that is and .
For more details, refer to the .
Send the , , and identifiers to your backend.
Use a to attach the source to the customer. It flips the source's 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 and .
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 , 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 .
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 and indicate that no future billing will occur.
To delete a subscription, retrieve its unique identifier, and pass it as a path parameter in a request.
A successful request results in the creation of an with a of .
If you want to stop recurring payments on an , you can or .
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 of 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 and as well as make updates to any of its following attributes:
A successful request results in the creation of an with a of .
For details on handling subscription updates in free trials, refer to in the section.
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.
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 to Digital River.
If you want to modify the timing of a subscription's , 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.
For details, refer to the section.
For details, refer to or .
When any of your receive an whose is , parse its payload to determine whether the contains a subscriptionId. If it does, you should cancel the subscription to avoid further chargebacks and fees.
