Subscriptions

Learn more about the subscriptions resource

On this page, you'll find information on:

The subscriptions resource

The following describes some of the key attributes in a subscription.

Binding period

The contractBindingUntil attribute represents the date and time when the subscription's contract expires. It's determined by adding the plan's contractBindingDays to the subscription's activation date.

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 is cancelled, ended, lapsed, or failed.

It's assumed, however, that your integration will allow customers to cancel a subscription once the contractBindingUntil date elapses. Failing to honor a customer's valid cancellation request makes you vulnerable to chargebacks.

When a customer wants to cancel a subscription prior to 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 section.

Plan identifier

The planId uniquely identifies the plan that the subscription belongs to.

Billing agreement identifier

For more information on the billingAgreementId, refer to the billing agreements section on the Subscription information page.

Customer and source identifiers

The customerId and sourceId are inherited from the acquisition order.

Tax inclusivity

The taxInclusive value is inherited from the acquisition order.

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 interval, equals the subscription's currentPeriodEndDate.

Current period end date

The currentPeriodEndDate represents the date and time when the subscription's current billing period ends. Subtracting the plan's interval from this value gives you the subscription's currentPeriodStartDate.

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 and starts attempting to capture payment. The value is determined by subtracting the plan's billingOffsetDays from the subscription's currentPeriodEndDate.

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 with a type of subscription.reminder.

Lifecycle of a subscription

Once the acquisition checkout is created, Digital River determines whether the plan is active, and, if it is, creates a subscription whose state is draft.

After you activate the subscription, we determine whether (1) the acquisition order exists, (2) its state is accepted and (3) the subscription's payment source remains valid. If these conditions are met, we move the subscription's state to either active or activeFree.

For details about activeFree, refer to Using free trials.

On the subscription's nextReminderDate, Digital River retrieves data from the resource and uses it to create a draft invoice. We then add subscription and invoice to the data.object of an event with a type of subscription.reminder.

On the subscription's nextInvoiceDate, Digital River checks the invoice's 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 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, the subscription transitions to active and 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 is still attempting to collect payment.

The service continues making billing attempts until either (1) payment is successfully captured or (2) the collection period elapses. A successful billing attempt moves the subscription's state to active and triggers the creation of subscription.extended. If the invoice is ultimately uncollectible, then the subscription's state becomes failed, which is a terminal condition, and 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, then state remains active and the subscription continues billing. But if you deactivate a subscription's plan, then state becomes ended on its nextInvoiceDate, at which point recurring billing permanently stops.

If we can’t create a billing invoice because it's determined that the subscription's designated source has a problem, then 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 of the subscription’s plan), then state moves to lapsed.

The remaining terminal state is cancelled, which means that a cancel subscription request 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 created

becomes draft

the subscription is activated

switches to active or activeFree

Digital River synchronously or asynchronously captures a recurring payment

becomes active

Digital River cannot immediately capture a recurring payment

switches to activePendingInvoice

--

Digital River fails to capture a recurring payment

switches to failed

Digital River determines that the subscription's source is invalid

remains active

An invalid source is not replaced during the grace period

moves to lapsed

the subscription cancelled

moves to cancelled

the subscription's plan is deactivated

switches to ended on nextInvoiceDate

--

the subscription is deleted

(subscription no longer exists)

Last updated