Managing subscriptions

Learn how to set up and renew subscriptions.

If you sell your product or service as part of a subscription, you must provide us subscription information. As reseller of record, Digital River is required to collect this basic data.

This data, along with the type of charge used to initiate the transaction, is what you'll use to set up and renew subscriptions.

Setting subscription information

If the transaction involves a subscription, you're required to include subscriptionInfo in the items array of a create or update Checkout request.

The following POST/checkouts request includes the subscription parameters related to auto renewals, free trials, and the terms displayed to the customer. You can also provide the subscription or the billing agreement identifier. For subscriptions that use the Klarna payment method, you're required to specify a start and end time.

cURL
cURL
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
--data-raw '{
"customerId": 519552880336,
...
"items": [
{
"skuId": "bc4aab24-2880-4de7-b6b0-07dd6e6841a9",
"price": 20.00,
"quantity": 2,
"subscriptionInfo": {
"autoRenewal": true,
"freeTrial": true,
"terms": "Please accept terms"
}
}
]
}'

Auto renewal

Use the autoRenewal parameter to tell us whether the subscription is automatically or manually renewed. If true, customers must have agreed to have their card information stored on file and charged at the start of every billing cycle. To do this, you must, at a minimum, attach a Source to the Customer associated with the subscription and make sure the Source is reusable.

If false, then the customer needs to manually renew the subscription. This means the customer must resupply payment data, which you may then use to create a new payment source that can be charged.

Free trial

When you offer customers a free trial period to test run the membership, but you also collect their credit card information, ensure that you set the freeTrial attribute to true. Digital River needs to know that credit card details are being collected, even when a charge does not occur.

Terms

Use the terms parameter to provide the subscription's auto-renewal terms that are displayed to the customer at the point of acquisition.

Subscription identifier

At the time of acquisition, your subscription management system, not Digital River, assigns the subscriptionId and passes the value in a POST/checkouts request.

Whenever you process a renewal, give us the same subscriptionId you provided at the point of acquisition. If the values don't match, however, we treat the request as a subscription acquisition rather than a renewal.

Billing agreement identifier

As part of the PSD2 Strong Customer Authentication (SCA) initiative, payment processors require extra information when processing merchant-initiated credit card transactions. To ensure that you adhere to the new mandate, you'll need to make use of billing agreements.

A billing agreement consists of the terms customers agree to when they consent to have their credit card details applied to any type of recurring purchase. The identifier of the agreement is then referenced on subsequent renewals.

Creating a billing agreement

You'll first need to ensure that you've attached a source to the customer associated with the subscription and that the source is reusable.

You'll then associate the customer with the checkout in a POST/checkouts or POST/checkouts/{id} request that includes the subscriptionInfo hash table.

After you use the checkout identifier to create an Order, Digital River generates a billing agreement and returns the billingAgreementId in the POST/orders response.

A one-to-one relationship exists between a subscription item and a billing agreement. For example, if your POST/orders request contains two line items and both have a subscriptionInfo hash table, then Digital River creates two separate billing agreements and returns two billing agreement identifiers.

For each subscription that you create, you should persist the billingAgreementId that is returned in the response. This is so that you can later provide the value when renewing the subscription.

Using the billing agreement identifier

When it's time to process a renewal, retrieve the billingAgreementId you persisted for that subscription. You should then include the value in the subscriptionInfo hash table of a POST Checkout request.

You should submit the same billingAgreementId when renewing the subscription, even if the customer is using a different credit card to pay for the transaction.

Finally, pass the checkout identifier returned in the response to a create Order request. Continue to persist the same billingAgreementId for future renewals.

Start and end time

When you create or renew subscriptions in the Digital River API, the start date is typically the current date and the end date is open-ended, meaning you're not required to specify a value for either.

Klarna, however, requires extra merchant data. So to create a subscription using this payment method, you must provide both a startTime and endTime. These data points help Klarna's risk engine make an accurate assessment of an order's validity, thereby improving conversion and acceptance rates.

For auto renewing subscriptions, at the point of acquisition, you should specify the startTime as the current date. The endTime should be the startTime + the subscription duration, also known as the payment schedule.

The payment schedule is how often customers pay for their subscription. For example, customers can have a year-long subscription that they pay monthly.

In the Digital River API, the subscription duration and payment schedule are treated as equivalent.

Use the ISO 8601 format to provide the startTime and endTime. If the values are improperly formatted, you'll receive an error code of invalid_parameter.

As an example, for an annual recurring subscription, if the startTime is 2020-05-21T00:00:00-05:00 then set the endTime to 2021-05-20T11:59:59-05:00. For a monthly recurring subscription with the same startTime, you would set the endTime to 2020-06-20T11:59:59-05:00.

So, to renew an open-ended subscription with a monthly payment (such as those offered by Netflix), you would send a POST/checkouts request on a monthly basis, updating the startDate and endDate in each request, until the customer cancels.

Creating and renewing subscriptions

Subscriptions are created and renewed using either a POST/checkouts or POST/checkouts/{id} request.

In both request types, you need to provide the subscriptionInfo and chargeType parameters. The values you submit however depend on whether you're creating a new subscription or auto-renewing an existing subscription.

Subscription acquisition

For acquisitions, the subscription information should include the autoRenewal, subscriptionId, and terms parameters. The type of charge should be set to customer_initiated to indicate a new subscription purchase.

cURL
cURL
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
--data-raw '{
...
"chargeType": "customer_initiated",
...
"items": [
{
...
"subscriptionInfo": {
"autoRenewal": true,
"subscriptionId": "59799e1c-7ae3-42f9-84c4-617efc578026",
"terms": "Insert terms here"
}
}
]
}'

Subscription auto-renewal

For server-initiated auto-renewals, the required subscription information is autoRenewal, and either thesubscriptionId you provided at the time of acquisition or the billing agreement identifier that you persisted. You should also set the type of charge tomerchant_initiated to indicate this is a renewal request.

cURL
cURL
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: <API_key>' \
--data-raw '{
...
"chargeType": "merchant_initiated",
...
"items": [
{
...
"subscriptionInfo": {
"autoRenewal": true,
"subscriptionId": "59799e1c-7ae3-42f9-84c4-617efc578026"
}
}
]
}'