# Subscription information

As [reseller of record](https://docs.digitalriver.com/digital-river-api/general-resources/glossary#merchant-of-record-seller-of-record-mor-sor), Digital River is required to collect basic subscription data. As a result, all [checkouts ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)that contain recurring products or services must have `subscriptionInfo`.

A checkout's `subscriptionInfo` can be used to hold data on:

* [Auto renewals](#auto-renewal)
* [Free trials](#free-trial)
* [Contractual terms](#terms)
* [Subscription identifiers](#subscription-identifier)
* [Billing agreements identifiers](#billing-agreements)
* [Start and end times](#start-and-end-time)

You'll use this data, along with the [charge type](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge), to set up and renew subscriptions.

We manage most of this data if you're using [Digital River's subscription service](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions). For integrations that use [third party subscription services](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/third-party-coordinated-subscriptions), you must supply these details in both acquisition and renewal [checkouts](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts).

{% tabs %}
{% tab title="Order" %}

```javascript
{
    "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"
            },
            ...
        }
    ],
    ...
}
```

{% endtab %}
{% endtabs %}

For server-initiated auto-renewals, the required `subscriptionInfo` configurations are `autoRenewal` set to `true`, the `subscriptionId` that you may have provided during the acquisition and the [`billingAgreementId`](#billing-agreements) from the acquisition [order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders). You should also set the checkout's [`chargeType`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/initiating-a-charge) to `merchant_initiated`.

## Auto renewal

The [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`autoRenewal` indicates whether subscriptions renew automatically or manually. Customers need to actively consent to automatic recurring billing during the acquisition of auto-renewing subscriptions. So, when `autorenewal` is `true`, customers must agree to have their payment information stored on file and then charged at the start of every billing cycle.‌

This setting is also necessary to display only [reusable payment methods](https://docs.digitalriver.com/digital-river-api/payments/supported-payment-methods) to customers.

For manual renewals, customers must be actively involved in the acquisition and renewal process. This means that customers supply payment information at the point of sale, which you use to either [create a new source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#creating-payment-sources) or [authenticate an existing source](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#authenticating-sources).

## Free trial

When you offer customers a free trial period to evaluate a subscription, and you also collect their payment information, make sure that you set the [checkout's ](https://app.gitbook.com/s/ScJM6Hp95yBCPfU1nBSB/checkouts)`freeTrial` to `true`. To satisfy our [reseller of record](https://docs.digitalriver.com/digital-river-api/general-resources/glossary#merchant-of-record-seller-of-record-mor-sor) requirements, Digital River needs to know that payment details are being collected, even when no charge authorization occurs.‌

If you're using [Digital River's subscription service](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions) and you want to offer no-charge trial subscriptions, `freeTrial` also need to be `true`. For details, refer to [Trial subscription acquisitions](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/digital-river-coordinated-subscriptions#managing-trial-subscription-acquisitions).

## Terms

The [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`terms` hold the subscription's contractual agreement. These should be the Digital River-approved terms displayed to customers during acquisitions. Before creating a subscription, your integration must acquire the customer's active acceptance of them. They define the subscription, provide links to Digital River's [terms of sale](https://store.digitalriver.com/store/defaults/en_US/DisplayDRTermsAndConditionsPage/eCommerceProvider.Digital%20River%20Inc.) and [privacy policy](https://store.digitalriver.com/store/defaults/en_US/DisplayDRPrivacyPolicyPage/eCommerceProvider.Digital%20River%20Inc.), 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)](https://docs.digitalriver.com/digital-river-api/payments/psd2-and-sca) initiative, payment processors require extra information when handling [merchant-initiated](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/initiating-a-charge#merchant-initiated) credit card transactions. To comply with this mandate, we make use of billing agreements.

A billing agreement contains, among other things, the [terms and conditions](#terms) 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 comply with relevant PSD2 SCA mandates, and we can make payment authorization requests that are more likely to succeed.‌

When you [convert a checkout to an order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier), and that checkout contains a [line item](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/describing-the-items) with `subscriptionInfo`, we create a billing agreement and return its `billingAgreementId` in the [`POST /orders`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders#orders-1) response.

{% hint style="info" %}
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 `subscriptionInfo` (i.e., both are subscriptions), then Digital River generates two separate billing agreements and returns two billing agreement identifiers.‌
{% endhint %}

If you're using [Digital River's subscription service](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions), we associate the billing agreement with the [subscription](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/digital-river-coordinated-subscriptions#billing-agreement-identifier) and make sure `billingAgreementId` is sent in all renewal requests. For those using a [third-party subscription service](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/third-party-coordinated-subscriptions), you must retrieve `billingAgreementId` from the acquisition [order ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)and pass it in all renewal requests.

## Subscription identifier

The [checkout's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/checkouts)`subscriptionId` field identifies a subscription.

If you're using [Digital River's subscription service](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions), you can pass your own `subscriptionId`. If you don't, we generate an identifier for you. In either case, the value uniquely identifies the [subscription](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/digital-river-coordinated-subscriptions#the-subscriptions-object) in our system.

If you're using a [third-party subscription service](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/third-party-coordinated-subscriptions), Digital River doesn't generate a `subscriptionId`. You must send your own value during the [checkout process](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts). In this case, whenever you process a renewal, it's best practice to provide us with the same `subscriptionId`  information you sent during the acquisition.

## Start and end time

​To create an auto-renewing subscription using [Klarna](https://docs.digitalriver.com/digital-river-api/payments/payment-integrations-1/digitalriver.js/payment-methods/klarna), you must provide both a `startTime` and `endTime`. This data helps Klarna's risk engine accurately assess a transaction's validity, improving conversion and acceptance rates.‌

When defining `startTime` and `endTime`, make sure you adhere to the [date/time standard](https://app.gitbook.com/s/ZrhMyLX5esFYS64lNWVW/digital-river-api-reference-guide/api-structure#dates-and-times) in the Digital River APIs. If either value is improperly formatted, you receive a `400 Bad Request` with an error `code` of `invalid_parameter`.

{% tabs %}
{% tab title="400 Bad Request" %}

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

{% endtab %}
{% endtabs %}

During acquisitions, 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 subscriptions. For example, customers might have a year-long subscription that they pay monthly. We treat the subscription duration and payment schedule as equivalent.‌

For example, if the `startTime` of an annually billed subscription is `2021-07-07T13:47:13Z` then 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`.‌

To renew an open-ended subscription that bills monthly, [build a checkout](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts), and [convert that checkout to an order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#creating-an-order-with-the-checkout-identifier) every month, updating `startDate` and `endDate` in each request until the customer cancels.‌