Subscriptions
Gain a better understanding of Digital River's subscription service along with how to define a business model and set up free trials
Digital River offers a PSD2 and SCA compliant subscription management service that automatically schedules and processes recurring payments. The service gives you the ability to offer customers free trials as well as numerous ways to fund recurring transactions.
On this page, you'll find information on:
How you do subscription acquisitions depends on the checkout solution(s) you've selected. Use the following table to access the appropriate article:
Checkout solution | Article |
|---|---|
Once the acquisition order that contains the subscription is created, you'll also need to activate the subscription, fulfill the goods, and manage renewals. For details on how to handle these, and other processes, refer to the Subscription management page.
In the subscription service, digital products can be shared among plans. We recommend not relying on SKUs to model subscription entitlements. We also suggest using different plans for your offerings since they can be used to model cohorts for reporting purposes.
Digital River's subscription service models recurring billing. It's not intended to model subscription access or entitlements. As a result, you cannot call the service to determine a customer's current access level.
Subscription metadata and client data linked to the subscription is useful for modeling details that are irrelevant to Digital River and within the plan's terms.
With Digital River's subscription service, you can either use SKUs or
productDetails to define the basic and compliance data of any digital product that you intend to offer on a subscription-basis.Once you've built a product catalog, you should set up plans that define the behavior of your subscriptions.
At a minimum, you should specify a plan's name and terms, designate its contract length and billing frequency, set up renewal reminders, and configure its billing offset days and collection period days.
The following diagram shows how plans define the behavior of subscriptions that belong to them.
In a
POST /plans request, you can set state to draft or active. If you're using Digital River as the system of record prior to deployment, you may decide its beneficial to create draft plans. If you don't specify a unique id in the create plan request, we generate one for you.curl --location --request POST 'https://api.digitalriver.com/plans' \
...
--data-raw '{
"name": "Example Plan",
"terms": "These are the terms...",
"contractBindingDays": 365,
"interval": "year",
"intervalCount": 1,
"reminderOffsetDays": 30,
"billingOffsetDays": 5,
"collectionPeriodDays":30,
"state": "draft"
}'
A
201 Created response contains a unique plan identifier. The request also triggers an event with a type of plan.created. If the plan's state is draft when you're ready to launch, send its identifier as a path parameter in a POST /plans/{planId} and use the request's body to set state to active.curl --location --request POST 'https://api.digitalriver.com/plans/173577b2-6edc-4f68-9297-7f7bc2ca6e58' \
...
--data-raw '{
"state": "active"
}'
The plan must be
active before you can add subscriptions to it. For details, refer to lifecycle of a plan and lifecycle of a subscription.Subscriptions on discontinued plans continue renewing. Deactivating a plan, however, terminates all of its active subscriptions on their
nextInvoiceDate.When you want to discontinue or deactivate a plan, specify the desired
state in the payload of a POST /plans/{planId} request.Discontinue
Deactivate
curl --location --request POST 'https://api.digitalriver.com/plans/173577b2-6edc-4f68-9297-7f7bc2ca6e58' \
...
--data-raw '{
"state": "discontinued"
}'
curl --location --request POST 'https://api.digitalriver.com/plans/173577b2-6edc-4f68-9297-7f7bc2ca6e58' \
...
--data-raw '{
"state": "deactivated"
}'
If you attempt to create subscriptions that belong to
discontinued or deactivated plans, an error is thrown during the acquisition checkout.400 Bad Request
{
"type": "bad_request",
"errors": [
{
"code": "plan_not_active",
"parameter": "planId",
"message": "Plan 86a05e42-3b94-4ee5-b2a5-267efd8b3704 is not active."
}
]
}
For details on how discontinuing or deactivating a plan affects its associated subscriptions, refer to lifecycle of a plan and lifecycle of a subscription.
You can configure a customer's subscription so that it starts with a free trial period. In this section, you'll find information on defining trial and paid plans prior to deployment.
How you handle subscription acquisitions that involve free trials depends on the checkout solution(s) you've selected. Use the following table to access the relevant content:
Once the acquisition order that contains the subscription is created, you'll also need to convert the subscription from trial to paid. For details, refer to Trial subscription management on the Subscription management page.
If you'd like to offer free trials, prior to deployment you'll need to configure plans for your trial subscriptions.
For each subscription you intend to offer on a trial basis, you should define a trial period plan and a paid period plan. The following diagram shows how you might set up two plans that result in a seven-day free trial period followed by a monthly, recurring billing cycle:
The plan's
interval and intervalCount determine the trial period's length. If, for example, you want to offer a 31-day free trial period, set interval to day and intervalCount to 31 .For free trial plans, set
billingOffsetDays to 0. This configuration results in a subscription whose initial billing cycle has the same nextInvoiceDate and currentPeriodEndDate, thereby ensuring that the first payment capture attempt occurs after the trial period is over.The value you give
reminderOffsetDays determines when the subscription.reminder event is created. For example, a reminderOffsetDays of 3 results in the creation of a subscription.reminder event three days before the trial period's conclusion.Use
collectionPeriodDays to define the number of days that Digital River should attempt to capture payment. Once the trial period is over, Digital River will make an initial attempt to charge the customer's designated payment source. If this proves unsuccessful, our billing optimization service continues making capture attempts for the number of days you specify.Plan
{
"id": "186cf07e-a1ea-4ec0-9d9a-8aa93b3af43a",
"createdTime": "2022-02-11T14:41:43Z",
"updatedTime": "2022-02-11T14:41:43Z",
"terms": "7-day free trial plan terms",
"contractBindingDays": 7,
"interval": "day",
"intervalCount": 7,
"name": "7-day SaaS free trial",
"billingOptimization": true,
"billingOffsetDays": 0,
"collectionPeriodDays": 4,
"reminderOffsetDays": 3,
"state": "active",
"stateTransitions": {
"activated": "2022-02-11T14:41:43Z"
},
"liveMode": false
}
You also need to define a paid period plan that governs the subscription after its trial conversion. On the following plan, customers are billed monthly, and, in every billing cycle, Digital River makes the first payment capture attempt three days before the end period date.
Plan
{
"id": "f55d07a2-a78f-406a-b6c6-ad8e1cc1531b",
"createdTime": "2022-02-11T14:42:53Z",
"updatedTime": "2022-02-11T14:42:53Z",
"terms": "The terms of a one-year plan that is billed monthly",
"contractBindingDays": 365,
"interval": "month",
"intervalCount": 1,
"name": "SaaS monthly billing plan",
"billingOptimization": true,
"billingOffsetDays": 3,
"collectionPeriodDays": 7,
"reminderOffsetDays": 4,
"state": "active",
"stateTransitions": {
"activated": "2022-02-11T14:42:53Z"
},
"liveMode": false
}
When setting up payment in acquisitions or modifying a subscription's payment source, customers must select from payment methods that can be used in recurring transactions.
In acquisition checkouts, you do have the option of combining a reusable primary source with one or more secondary sources. For details, refer to combining primary and secondary payment sources on the Managing sources page
Last modified 3mo ago