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 | (3) and an event with a |
the acquisition checkout is created | becomes | |
the subscription is activated | switches to | |
Digital River synchronously or asynchronously captures a recurring payment | becomes | |
Digital River cannot immediately capture a recurring payment | switches to | -- |
Digital River fails to capture a recurring payment | switches to | |
Digital River determines that the subscription's source is invalid | remains | |
An invalid source is not replaced during the grace period | moves to | |
the subscription cancelled | moves to | |
the subscription's plan is deactivated | switches to | -- |
the subscription is deleted | (subscription no longer exists) |
Last updated
