> For the complete documentation index, see [llms.txt](https://docs.digitalriver.com/digital-river-api-reference/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/subscriptions/subscription-basics.md). # 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](/digital-river-api-reference/2021-12-13/subscriptions.md). ### Binding period The `contractBindingUntil` attribute represents the date and time when the subscription's contract expires. It's determined by adding the [plan's](/digital-river-api-reference/2021-12-13/plans.md) [`contractBindingDays` ](/digital-river-api-reference/2021-12-13/plans/plan-basics.md#contract-length-and-interval)to the [subscription's activation date](https://docs.digitalriver.com/digital-river-api/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://docs.digitalriver.com/digital-river-api/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://docs.digitalriver.com/digital-river-api/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 ](/digital-river-api-reference/2021-12-13/plans/plan-basics.md)that the subscription belongs to. ### Billing agreement identifier For more information on the `billingAgreementId`, refer to the [billing agreements](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/subscription-information-1#billing-agreements) section on the [Subscription information](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/subscriptions/subscription-information-1) page. ### Customer and source identifiers The [`customerId` ](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/using-the-checkout-identifier#registered-checkouts-or-invoices)and [`sourceId` ](https://docs.digitalriver.com/digital-river-api/payments/payment-sources/using-the-source-identifier)are inherited from the acquisition [order](/digital-river-api-reference/2021-12-13/orders.md). ### Tax inclusivity The [`taxInclusive` ](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/creating-checkouts/configuring-taxes)value is inherited from the acquisition [order](/digital-river-api-reference/2021-12-13/orders.md). ### 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 ](/digital-river-api-reference/2021-12-13/plans/plan-basics.md)`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 ](/digital-river-api-reference/2021-12-13/plans/plan-basics.md)[`interval` ](/digital-river-api-reference/2021-12-13/plans/plan-basics.md#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](/digital-river-api-reference/2021-12-13/invoices/invoice-basics.md#invoice-states) and attempts to capture payment. The value is determined by subtracting the [plan's ](/digital-river-api-reference/2021-12-13/plans/plan-basics.md)[`billingOffsetDays`](/digital-river-api-reference/2021-12-13/plans/plan-basics.md#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](/digital-river-api-reference/2021-12-13/events.md) with a [`type` ](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types)of [**`subscription.reminder`**](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/subscriptions/spaces/-LqH4RJfLVLuHPXuJyTZ/pages/okHqAQ9d1PaLPLjq6nZF#subscription.reminder). ## Subscription lifecycle Once the acquisition [checkout ](/digital-river-api-reference/2021-12-13/checkouts.md)is created, Digital River determines whether the [plan ](/digital-river-api-reference/2021-12-13/plans.md)is [`active`](/digital-river-api-reference/2021-12-13/plans/plan-basics.md#state), and, if it is, creates a subscription whose `state` is `draft`. After you [activate the subscription](https://docs.digitalriver.com/digital-river-api/subscription-management/managing-a-subscription#activating-a-subscription), we determine whether (1) the acquisition [order](/digital-river-api-reference/2021-12-13/orders.md) exists, (2) its [`state` ](/digital-river-api-reference/2021-12-13/orders/order-basics.md#order-states-and-events)is `accepted` and (3) the subscription's [payment source](https://docs.digitalriver.com/digital-river-api/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://docs.digitalriver.com/digital-river-api/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](/digital-river-api-reference/2021-12-13/invoices.md#invoices). We then add `subscription` and [`invoice` ](/digital-river-api-reference/2021-12-13/invoices/invoice-basics.md)to the [`data.object`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-data) of an [event ](/digital-river-api-reference/2021-12-13/events.md)with a [`type` ](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types)of [`subscription.reminder`](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/subscriptions/spaces/-LqH4RJfLVLuHPXuJyTZ/pages/okHqAQ9d1PaLPLjq6nZF#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` ](/digital-river-api-reference/2021-12-13/invoices/invoice-basics.md#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`](/digital-river-api-reference/2021-12-13/invoices/invoice-basics.md#invoice-states), the subscription transitions to `active` and [`subscription.extended`](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/subscriptions/spaces/-LqH4RJfLVLuHPXuJyTZ/pages/okHqAQ9d1PaLPLjq6nZF#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](/digital-river-api-reference/2021-12-13/invoices/invoice-basics.md#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](/digital-river-api-reference/2021-12-13/plans/plan-basics.md#collection-period-days) elapses. A successful billing attempt moves the subscription's `state` to `active` and triggers the creation of [`subscription.extended`](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/subscriptions/spaces/-LqH4RJfLVLuHPXuJyTZ/pages/okHqAQ9d1PaLPLjq6nZF#subscription.extended). If the invoice is ultimately [`uncollectible`](/digital-river-api-reference/2021-12-13/invoices/invoice-basics.md#invoice-states), then the subscription's `state` becomes `failed`, which is a terminal condition, and [`subscription.failed`](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/subscriptions/spaces/-LqH4RJfLVLuHPXuJyTZ/pages/okHqAQ9d1PaLPLjq6nZF#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://docs.digitalriver.com/digital-river-api/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://docs.digitalriver.com/digital-river-api/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](/digital-river-api-reference/2021-12-13/invoices/invoice-basics.md) because it's determined that the subscription's designated source has a problem, then [`subscription.source_invalid`](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/subscriptions/spaces/-LqH4RJfLVLuHPXuJyTZ/pages/okHqAQ9d1PaLPLjq6nZF#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` ](/digital-river-api-reference/2021-12-13/plans/plan-basics.md#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://docs.digitalriver.com/digital-river-api/subscription-management/managing-a-subscription#cancelling-a-subscription) has been successfully submitted.
The following table looks at what precedes a subscription `state` change and which types of events (if any) are created as a result:
(1) When...(2) the subscription's state...(3) and an event with a type of ... is created.
the acquisition checkout is createdbecomes draftsubscription.created
the subscription is activatedswitches to active or activeFreesubscription.updated
Digital River synchronously or asynchronously captures a recurring paymentbecomes activesubscription.extended
Digital River cannot immediately capture a recurring paymentswitches to activePendingInvoice--
Digital River fails to capture a recurring paymentswitches to failedsubscription.failed
Digital River determines that the subscription's source is invalidremains activesubscription.source_invalid
An invalid source is not replaced during the grace periodmoves to lapsedsubscription.lapsed
the subscription cancelledmoves to cancelledsubscription.updated
the subscription's plan is deactivatedswitches to ended on nextInvoiceDate--
the subscription is deleted(subscription no longer exists)subscription.deleted