# 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
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/subscriptions/subscription-basics.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.