# Subscription basics

On this page, you'll find information on:

* [The subscriptions resource](#the-subscriptions-resource)
* [The subscription lifecylce](#subscription-lifecycle)

## The subscriptions resource

The following describes some of the key attributes in a [subscription](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/subscriptions).

### Binding period

The `contractBindingUntil` attribute represents the date and time when the subscription's contract expires. It's determined by adding the [plan's](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/plans) [`contractBindingDays` ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/plans/plan-basics#contract-length-and-interval)to the [subscription's activation date](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/subscription-management/managing-a-subscription).

The data in this field doesn't drive any logic. Instead, it exists for compliance and transparency purposes. All subscriptions are open-ended. This means that they keep billing until the subscription's [`state`](#state) is `cancelled`, `ended`, `lapsed`, or `failed`.

It's assumed, however, that your integration will allow customers to [cancel a subscription](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/subscription-management/managing-a-subscription#cancelling-a-subscription) once the `contractBindingUntil` date elapses. Failing to honor a customer's valid cancellation request makes you vulnerable to [chargebacks](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/returns-and-refunds-1/disputes-and-chargebacks).

When a customer wants to cancel a subscription before the `contractBindingUntil` date, it's up to the client system to decide whether to honor the request.

### State

For details, refer to the [lifecycle of a subscription](#lifecycle-of-a-subscription) section.

### Plan identifier

The `planId` uniquely identifies the [plan ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/plans/plan-basics)that the subscription belongs to.

### Billing agreement identifier

For more information on the `billingAgreementId`, refer to the [billing agreements](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/integration-options/checkouts/subscriptions/subscription-information-1#billing-agreements) section on the [Subscription information](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/integration-options/checkouts/subscriptions/subscription-information-1) page.

### Customer and source identifiers

The [`customerId` ](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/integration-options/checkouts/creating-checkouts/using-the-checkout-identifier#registered-checkouts-or-invoices)and [`sourceId` ](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/payments/payment-sources/using-the-source-identifier)are inherited from the acquisition [order](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/orders).

### Tax inclusivity

The [`taxInclusive` ](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/integration-options/checkouts/creating-checkouts/configuring-taxes)value is inherited from the acquisition [order](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/orders).

### Subscription products and services

The price, quantity, and SKU identifier of the subscription's products and services are contained in `items[]`.

### Current period start date

The `currentPeriodStartDate` represents the date and time when the subscription's current billing period began. This value, added to the [plan's ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/plans/plan-basics)`interval`, equals the subscription's [`currentPeriodEndDate`](#current-period-end-date).

### Current period end date

The `currentPeriodEndDate` represents the date and time when the subscription's current billing period ends. Subtracting the [plan's ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/plans/plan-basics)[`interval` ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/plans/plan-basics#contract-length-and-interval)from this value gives you the subscription's [`currentPeriodStartDate`](#current-period-start-date).

### Date of next invoice

The `nextInvoiceDate` represents the date and time of the next billing attempt. It's when Digital River [opens a new invoice](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices/invoice-basics#invoice-states) and attempts to capture payment. The value is determined by subtracting the [plan's ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/plans/plan-basics)[`billingOffsetDays`](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/plans/plan-basics#billing-offset) from the subscription's [`currentPeriodEndDate`](#current-period-end-date).

For example, a subscription with a `currentPeriodEndDate` of `2021-08-06T00:00:00.0000000Z` that belongs to a plan with a `billingOffsetDays` of `5`, will have a `nextInvoiceDate` of `2021-08-01T00:00:00.0000000Z`.

### Date of next reminder

The `nextReminderDate` is the date and time when Digital River creates an [event](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/events) with a [`type` ](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1#event-types)of [**`subscription.reminder`**](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1/event-types#subscription.reminder).

## Subscription lifecycle

Once the acquisition [checkout ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/checkouts)is created, Digital River determines whether the [plan ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/plans)is [`active`](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/plans/plan-basics#state), and, if it is, creates a subscription whose `state` is `draft`.

After you [activate the subscription](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/subscription-management/managing-a-subscription#activating-a-subscription), we determine whether (1) the acquisition [order](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/orders) exists, (2) its [`state` ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/orders/order-basics#order-states-and-events)is `accepted` and (3) the subscription's [payment source](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/payments/payment-sources) remains valid. If these conditions are met, we will move the subscription's `state` to either `active` or `activeFree`.

{% hint style="info" %}
For details about `activeFree`, refer to [Setting up free trials](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/using-our-services/subscriptions#setting-up-subscription-based-products).
{% endhint %}

On the subscription's [`nextReminderDate`](#date-of-next-reminder), Digital River retrieves data from the resource and uses it to create a [`draft` invoice](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices#invoices). We then add `subscription` and [`invoice` ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices/invoice-basics)to the [`data.object`](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1#event-data) of an [event ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/events)with a [`type` ](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1#event-types)of [`subscription.reminder`](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1/event-types#subscription.reminder).

On the subscription's [`nextInvoiceDate`](#date-of-next-invoice), Digital River checks the [invoice's](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Invoices) `totalAmount`. If its `0`, then this indicates that the subscription's free trial period has either been extended or reactivated and, as a result, we don't make any payment collection attempts, and the subscription's `state` either remains or becomes `activeFree`.

If the invoice's `totalAmount` is greater than `0`, then we move its [`state` ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices/invoice-basics#invoice-states)to `open`, which initiates the billing process and pushes the subscription's `state` to `activePendingInvoice`.

If we immediately capture payment, then the invoice becomes [`paid`](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices/invoice-basics#invoice-states), the subscription transitions to `active` and [`subscription.extended`](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1/event-types#subscription.extended) is triggered.

If we're unable to synchronously capture payment, then the subscription's `state` remains `activePendingInvoice`. This indicates that our [smart auto-renewal service](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices/invoice-basics#invoice-billing) is still attempting to collect payment.

The service continues making billing attempts until either (1) payment is successfully captured or (2) the [collection period](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/plans/plan-basics#collection-period-days) elapses. A successful billing attempt moves the subscription's `state` to `active` and triggers the creation of [`subscription.extended`](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1/event-types#subscription.extended). If the invoice is ultimately [`uncollectible`](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices/invoice-basics#invoice-states), then the subscription's `state` becomes `failed`, which is a terminal condition, and [`subscription.failed`](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1/event-types#subscription.failed) is created.

Three other terminal states might occur during a subscription's lifecycle: `ended`, `lapsed`, and `cancelled`.

If you [discontinue a subscription's plan](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/using-our-services/subscriptions#discontinuing-and-deactivating-plans), then `state` remains `active` and the subscription continues billing. But if you [deactivate a subscription's plan](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/using-our-services/subscriptions#discontinuing-and-deactivating-plans), then `state` becomes `ended` on its [`nextInvoiceDate`](#date-of-next-invoice), at which point recurring billing permanently stops.

If we can’t create a [billing invoice](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/invoices/invoice-basics) because it's determined that the subscription's designated source has a problem, then [`subscription.source_invalid`](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1/event-types#subscription.source_invalid) is triggered, but the subscription's `state` remains `active`. However, if the invalid source isn’t replaced at some point during the grace period (i.e., the [`collectionPeriodDays` ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/plans/plan-basics#collection-period-days)of the subscription’s plan), then `state` moves to `lapsed`.

The remaining terminal `state` is `cancelled`, which means that a [cancel subscription request](https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/subscription-management/managing-a-subscription#cancelling-a-subscription) has been successfully submitted.

<figure><img src="https://567528635-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fx8fSFzVR3sg0TsNWwwVz%2Fuploads%2F26Ud8W6cCJKhjgOT7S7u%2FSubscription%20lifecycle.png?alt=media&#x26;token=fa1fad57-0d6c-4d6f-8731-832d394772be" alt=""><figcaption></figcaption></figure>

The following table looks at what precedes a subscription `state` change and which types of events (if any) are created as a result:

<table data-header-hidden><thead><tr><th width="308"></th><th width="218.33333333333331"></th><th></th></tr></thead><tbody><tr><td>(1) When...</td><td>(2) the subscription's <code>state</code>...</td><td>(3) and an event with a <code>type</code> of ... is created.</td></tr><tr><td>the acquisition <a href="../checkouts">checkout </a>is created</td><td>becomes <code>draft</code></td><td><a href="https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1/event-types#subscription.created"><code>subscription.created</code></a></td></tr><tr><td>the subscription is activated</td><td>switches to <code>active</code> or <code>activeFree</code></td><td><a href="https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1/event-types#subscription.updated"><code>subscription.updated</code></a></td></tr><tr><td>Digital River synchronously or asynchronously captures a recurring payment</td><td>becomes <code>active</code></td><td><a href="https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1/event-types#subscription.extended"><code>subscription.extended</code></a></td></tr><tr><td>Digital River <em>cannot</em> immediately capture a recurring payment</td><td>switches to <code>activePendingInvoice</code></td><td>--</td></tr><tr><td>Digital River fails to capture a recurring payment</td><td>switches to <code>failed</code></td><td><a href="https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1/event-types#subscription.failed"><code>subscription.failed</code></a></td></tr><tr><td>Digital River determines that the subscription's <a href="../sources">source </a>is invalid</td><td>remains <code>active</code></td><td><a href="https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1/event-types#subscription.source_invalid"><code>subscription.source_invalid</code></a></td></tr><tr><td>An invalid <a href="../sources">source </a>is not replaced during the grace period</td><td>moves to <code>lapsed</code></td><td><a href="https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1/event-types#subscription.lapsed"><code>subscription.lapsed</code></a></td></tr><tr><td>the subscription cancelled</td><td>moves to <code>cancelled</code></td><td><a href="https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1/event-types#subscription.updated"><code>subscription.updated</code></a></td></tr><tr><td>the subscription's plan is deactivated</td><td>switches to <code>ended</code> on <a href="#date-of-next-invoice"><code>nextInvoiceDate</code></a></td><td>--</td></tr><tr><td>the subscription is deleted</td><td><em>(subscription no longer exists)</em></td><td><a href="https://app.gitbook.com/s/-LqH4RJfLVLuHPXuJyTZ/order-management/events-and-webhooks-1/events-1/event-types#subscription.deleted"><code>subscription.deleted</code></a></td></tr></tbody></table>