Links

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, 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 the items[]. This data is inherited from the acquisition order.

Current period end date

The currentPeriodEndDate represents the date and time when the subscription's current billing period ends. It's determined by adding the plan's billing interval to the subscription's activation 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 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

Assuming the plan is active, Digital River creates a subscription whose state is draft after the acquisition checkout is created.
Once the order moves into an accepted state, and you either activate the subscription, Digital River determines whether the acquisition order exists and whether the subscription's payment source remains valid. If these validations prove successful, we move the subscription into either an active or activeFree state.
For more information about activeFree, refer to Using free trials.
On the subscription's nextReminderDate, Digital River retrieves data from the subscription and uses it to create a draft invoice. We then package the subscription and invoice data into a subscription.reminder event.
On the subscription's nextInvoiceDate, Digital River checks the invoice's totalAmount. If the value is 0, then this indicates that the subscription's free trial period has either been extended or reactivated and, as a result, Digital River doesn't make any payment collection attempts and the subscription either remains or becomes activeFree.
If the invoice's totalAmount is greater than 0, Digital River moves the invoice into an open state, thereby initiating the billing process. At this point, the subscription becomes activePendingInvoice.
If we synchronously capture payment, then the invoice becomes paid, the subscription immediately transitions to active and a subscription.extended event is triggered.
If we're unable to immediately capture payment, then the subscription's state remains activePendingInvoice. This indicates that our smart auto-renewal service is 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 into an active state and we send you a subscription.extended event . If the invoice is ultimately uncollectible, then the subscription enters a failed state and a subscription.failed event is fired.
There are two other terminal states that may occur in a subscription's lifecycle: ended and cancelled.
If you discontinue a subscription's plan, then its state remains active and it continues billing. A subscription is ended on its nextInvoiceDate when you deactivate its plan. In this case, recurring billing permanently stops.
The remaining terminal state is cancelled. This indicates that either you took the initiative to cancel the subscription or you cancelled it at the customer's request.
The following table looks at the events that precede a subscription state change and the resulting events that are fired:
(1) When...
(2) the subscription state...
(3) and a ... event is triggered.
the acquisition checkout is created
becomes draft
the subscription is activated
switches to active or activeFree
Digital River immediately captures a recurring payment
becomes active
Digital River cannot immediately capture a recurring payment
switches to activePendingInvoice
Digital River asynchronously captures a recurring payment
becomes active
Digital River fails to asynchronously capture a recurring payment
switches to failed
the subscription is cancelled
moves to cancelled
the subscription's plan is deactivated
switches to ended on nextInvoiceDate
the subscription is deleted
(subscription no longer exists)
Last modified 3mo ago