# Processing subscription acquisitions

If you're pairing either of Digital River's [low-code checkout solutions](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts) with [our subscription service](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions), this page explains how to process:

* [Standard subscription acquisitions](#building-acquisitions)
* [Trial subscription acquisitions](#managing-trial-subscription-acquisitions)

Once Digital River converts the [checkout-session](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/drop-in-checkout-sessions) to an [order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders), you must activate the subscription, fulfill the goods, and manage renewals. For details on handling these and other processes, refer to the [Managing a subscription ](https://docs.digitalriver.com/digital-river-api/subscription-management/managing-a-subscription)page.

## Subscription acquisitions <a href="#building-acquisitions" id="building-acquisitions"></a>

During a standard subscription acquisition, your [create checkout-session request](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/drop-in-checkout-sessions#drop-in-checkout-sessions) must pass `subscriptionInfo` in `items[]`.

For each `items[].subscriptionInfo` in the request:

* Use `planId` to associate the [subscription](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics) with a [plan](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics). For details, refer to [Defining a business model](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions#defining-a-business-model).
* Include `terms`. To do this, [get the plan that the subscription belongs to](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Plans) before submitting the request. From the response, retrieve the [plan's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics)`terms` and pass that value in the request.\
  \
  If you don't pass `terms`, a `400 Bad Request` with a `code` of `missing_parameter` is returned.
* Set `autoRenewal` to `true` or omit the value. If you set this parameter to `false`, a `400 Bad Request` with a `code` of `invalid_request` is returned.
* If you don't provide a unique `subscriptionId`, we generate one for you.

Your request must also pass a [`customerId` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/drop-in-checkout-sessions/checkout-sessions-basics#customer-identifier)and should specify a `chargeType` of `customer_initiated`.

Acquisition requests can also contain:

* [Multiple `items[]` with `subscriptionInfo`](#subscriptions-with-multiple-line-items)
* [A mix of both subscription and non-subscription `items[]`](#mixed-carts)

#### Multiple `items[]` with `subscriptionInfo` <a href="#subscriptions-with-multiple-line-items" id="subscriptions-with-multiple-line-items"></a>

Your [create checkout-session request](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/drop-in-checkout-sessions#drop-in-checkout-sessions) can contain multiple `items[]` with `subscriptionInfo`. However, all these recurring `items[]` have to share the same `planId` and (if you pass your own value) `subscriptionId`.

If your request contains multiple `items[]` with `subscriptionInfo` and they reference different [plans](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics), then the following error is returned:

{% tabs %}
{% tab title="409 Conflict" %}

```javascript
{
    "type": "conflict",
    "errors": [
        {
            "code": "plan_limit_reached",
            "parameter": "planId",
            "message": "Only one unique subscription plan can be supported in a checkout"
        }
    ]
}
```

{% endtab %}
{% endtabs %}

#### Mixed subscription and non-subscription `items[]` <a href="#mixed-carts" id="mixed-carts"></a>

Your [create checkout-session request](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/drop-in-checkout-sessions#drop-in-checkout-sessions) can also have a mix of `items[]`, some with and some without `subscriptionInfo`. This allows you to, for example, process transactions that combine purchasing a one-time physical product with a recurring digital subscription.

## Trial subscription acquisitions <a href="#managing-trial-subscription-acquisitions" id="managing-trial-subscription-acquisitions"></a>

You handle free-trial acquisitions in much the same way as [standard subscription acquisitions](#building-acquisitions).

However, in free trials, you must slightly modify your [create checkout-session request](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Drop-in-Checkout-Sessions/operation/createDropInCheckoutSession).

For each trial-based `items[]` in the request:

* Pass a `price` or `aggregatePrice` of `0.0`
* In its `subscriptionInfo`:
  * Set `freeTrial` to `true`
  * Pass a `planId` that references a [trial period plan](https://docs.digitalriver.com/digital-river-api/using-our-services/subscriptions#trial-period-plans).

If your request contains an `items[]` whose (1) `subscriptionInfo.freeTrial` is `true` and its `price` or `aggregatePrice` is greater than `0.0` or (2) whose `subscriptionInfo.freeTrial` is `false` and its `price` or `aggregatePrice` is `0.0`, then the following error is thrown:

{% code title="400 Bad Request" %}

```javascript
{
    "type": "bad_request",
    "errors": [
        {
            "code": "invalid_parameter",
            "parameter": "items",
            "message": "The value of the Free Trial flag is not consistent with the item price or the aggregate price."
        }
    ]
}
```

{% endcode %}

For details on processing a trial-based subscription after Digital River converts the acquisition [checkout-session](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/drop-in-checkout-sessions/checkout-sessions-basics) to an [order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders), refer to [Trial subscription management](https://docs.digitalriver.com/digital-river-api/subscription-management/managing-a-subscription#trial-subscription-management) on the [Subscription management](https://docs.digitalriver.com/digital-river-api/subscription-management/managing-a-subscription) page.

## How Digital River processes your requests <a href="#handling-the-response" id="handling-the-response"></a>

For each `items[]` with `subscriptionInfo` sent in the [create checkout-session request](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Drop-in-Checkout-Sessions/operation/createDropInCheckoutSession), Digital River creates a single [subscription](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions), sets its to [`state` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics#state)to `draft` and then generates an [event ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/events)with a [`type`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types) of [`subscription.created`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1/event-types#subscription.created).

{% hint style="info" %}
The event's [`data.object`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-data) doesn't contain [key subscription attributes](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions/subscription-basics) such as `contractBindingUntil`, `nextReminderDate`, `currentPeriodEndDate`, and `nextInvoiceDate`. These are populated after you [activate the subscription](https://docs.digitalriver.com/digital-river-api/subscription-management/managing-a-subscription#activating-a-subscription).
{% endhint %}

Digital River also presents customers with a localized, recurring billing agreement in the payment collection stage and forces them to accept it before they can submit the order.

{% tabs %}
{% tab title="Prebuilt Checkout" %}
{% hint style="success" %}
In [Prebuilt Checkout](https://docs.digitalriver.com/digital-river-api/integration-options/low-code-checkouts/drop-in-checkout), we retrieve the [`interval` and `intervalCount`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans/plan-basics#contract-length-and-interval) of the [plan](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/plans) that the [subscription](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/subscriptions) belongs to and present this information in the order summary section.
{% endhint %}

<div align="left"><figure><img src="https://334437993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LqH4RJfLVLuHPXuJyTZ%2Fuploads%2F5qaBffsNNYLW2Z7qqhkV%2Fimage.png?alt=media&#x26;token=75a0cfdd-276e-4f66-9ceb-56c14d97a3fc" alt=""><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="Payment Component" %}

<div align="left"><figure><img src="https://334437993-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LqH4RJfLVLuHPXuJyTZ%2Fuploads%2F08BECV50hUnAjQM8gq6Z%2Fimage.png?alt=media&#x26;token=f36dbfe9-99d6-4fc7-81fd-312e171ffc2d" alt=""><figcaption></figcaption></figure></div>
{% endtab %}
{% endtabs %}

To make the [primary payment `sources[]`](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier#primary-payment-sources) [reusable](https://docs.digitalriver.com/digital-river-api/payments/payment-sources#reusable-or-single-use), Digital River saves it to the [customer](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/customers) referenced by [`customerId`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/drop-in-checkout-sessions/checkout-sessions-basics#customer-identifier).

Refer to the[ Managing a subscription](https://docs.digitalriver.com/digital-river-api/subscription-management/managing-a-subscription) page to learn more about activating subscriptions and handling renewals.