Subscription information

Learn about Digital River's basic subscription configurations

As reseller of record, Digital River is required to collect basic subscription data. This means that all transactions containing recurring products or services must provide subscriptionInfo in the checkout.

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

If you're using Digital River's subscription service, we auto-populate and manage this information. For integrations that use third party subscription services, you must supply these details in both acquisition and renewal checkouts.

The subscriptionInfo block can contain information on auto renewals, free trials, contractual terms, subscription identifiers, billing agreement identifiers, and start and end times.

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.

Acquisition order
Acquisition order
{
"id": "192498520336",
...
"items": [
{
"id": "114400500336",
...
"subscriptionInfo": {
"subscriptionId": "acf73606-a8f1-4126-8156-0467e73ae4ae",
"terms": "Subscription terms accepted by the customer",
"autoRenewal": true,
"freeTrial": false,
"billingAgreementId": "0555aec0-2c75-4306-aa2b-4d102233f1f0",
"startTime": "2021-07-07T13:47:13Z",
"endTime": "2022-07-07T13:47:13Z"
},
...
}
],
...
}

Auto renewal

The checkout's autoRenewal field indicates whether the subscription renews automatically or manually. During the acquisition of auto-renewing subscriptions, customers need to actively consent to merchant-initiated recurring transactions. So, when autorenewal is true, customers must agree to have their card information stored on file and then charged at the start of every billing cycle.‌

This setting is also necessary to ensure that you only display reusable payment methods to the customer.

For manual renewals, customers must be actively involved in both the acquisition and renewal process. This means that at the point of sale, customers supply payment information, which you then use to either create a new source or authenticate an existing source.

Free trial

When you offer customers a free trial period to test run a membership, and you also collect their credit card information, make sure that you set a checkout's freeTrial to true. To satisfy our reseller of record requirements, Digital River needs to know that credit card details are being collected, even when no charge authorization occurs.‌

Terms

The checkout's terms field captures a subscription's contractual agreement. These are the Digital River approved terms displayed to the customer during the acquisition process. Prior to processing an acquisition, your integration must acquire the customer's active acceptance of these terms. They define the subscription, provide links to Digital River's terms of sale and privacy policy, and stipulate that the customer agrees to store their payment information for use in renewals.

Billing agreements

As part of the PSD2 Strong Customer Authentication (SCA) initiative, payment processors require extra information when handling merchant-initiated credit card transactions. To comply with this mandate, we make use of billing agreements.

Among other information, a billing agreement contains the terms and conditions agreed to by the customer during a subscription's acquisition. This agreement demonstrates that the customer consented to have their payment information saved and then used in recurring transactions.

By connecting the customer-initiated subscription acquisition with merchant-initiated autorenewals, you stay in compliance with the relevant PSD2 SCA mandates and we can make payment authorization requests that are more likely to succeed.‌

Billing agreements are generated by Digital River during the subscription's acquisition. More specifically, when you convert a checkout to an order, and that checkout contains a line item with subscriptionInfo, we create a billing agreement and return its billingAgreementId in the POST/orders response.

A one-to-one relationship exists between a subscription and a billing agreement. For example, if the transaction contains two line items and both have a subscriptionInfo hash table (i.e., both are subscriptions), then Digital River generates two separate billing agreements and returns two billing agreement identifiers.‌

If you're using Digital River's subscription service, we add the billing agreement to the subscription and make sure billingAgreementId is sent in all renewal requests. For those using a third-party subscription service, you need to persist billingAgreementId and ensure that it is included in all renewal requests.

Subscription identifier

The checkout's subscriptionId field identifies a subscription.

For integrations that use Digital River's subscription service, you can supply your own subscriptionId when describing a line item. If you don't, we generate an identifier for you. In either case, the value uniquely identifies the subscription.

If you're using a third-party subscription service, Digital River doesn't generate the subscriptionId. Your service must supply this value and pass it during the checkout process. In this case, whenever you process a renewal, its best practice to provide us the same subscriptionId you sent during the acquisition.

As an example, for an annual recurring subscription, if the startTime is 2021-07-07T13:47:13Z then you should set endTime to 2022-07-07T13:47:12Z. For a monthly recurring subscription with the same startTime, you would set endTime to 2022-08-07T13:47:12Z.‌

Start and end time

​To create an auto-renewing subscription using the Klarna payment method, you must provide both a startTime and endTime. These data points help Klarna's risk engine make an accurate assessment of an transaction's validity, thereby improving conversion and acceptance rates.‌

When defining a startTime and endTime, make sure you adhere to the ISO-8601 standard used in the Digital River APIs. If either value is improperly formatted, you receive a 400 Bad Request with an error code of invalid_parameter.

400 Bad Request
400 Bad Request
{
"type": "bad_request",
"errors": [
{
"code": "invalid_parameter",
"parameter": "endTime",
"message": "2021-06-07T13:47:13Zxyxy is not a valid timestamp."
}
]
}

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

During the acquisition process, you should specify 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. We treat the subscription duration and payment schedule as equivalent.‌

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",
"billingAgreementId": "1a39f03a-3553-4136-9d96-4690c19dc4bb"
}
}
]
}'

As an example, for an annual recurring subscription, if the startTime is 2021-07-07T13:47:13Z then you should set endTime to 2022-07-07T13:47:12Z. For a monthly recurring subscription with the same startTime, you would set endTime to 2021-08-07T13:47:12Z.‌

So, to renew an open-ended subscription with a monthly payment (such as those offered by Netflix), you would build a checkout and then convert that checkout to an order on a monthly basis, updating the startDate and endDate in each request, until the customer cancels.‌