Subscription basics
Learn more about the subscriptions resource.
Last updated
Learn more about the subscriptions resource.
Last updated
On this page, you'll find information on:
The following describes some of the key attributes in a subscription.
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 .
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 once the contractBindingUntil date elapses. Failing to honor a customer's valid cancellation request makes you vulnerable to .
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.
For details, refer to the lifecycle of a subscription section.
The planId uniquely identifies the plan that the subscription belongs to.
The price, quantity, and SKU identifier of the subscription's products and services are contained in items[].
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.
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.
The nextInvoiceDate represents the date and time of the next billing attempt. It's when Digital River opens a new invoice and attempts 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.
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.
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'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.
Three other terminal states might occur during a subscription's lifecycle: ended, lapsed, and cancelled.
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.
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
remains active
moves to lapsed
the subscription cancelled
moves to cancelled
the subscription's plan is deactivated
--
the subscription is deleted
(subscription no longer exists)
For more information on the billingAgreementId, refer to the section on the page.
The and are inherited from the acquisition order.
The value is inherited from the acquisition order.
The nextReminderDate is the date and time when Digital River creates an event with a of .
After you , we determine whether (1) the acquisition order exists, (2) its state is accepted and (3) the subscription's remains valid. If these conditions are met, we will move the subscription's state to either active or activeFree.
For details about activeFree, refer to .
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 of an event with a of .
If we immediately capture payment, then the invoice becomes paid, the subscription transitions to active and is triggered.
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 . If the invoice is ultimately uncollectible, then the subscription's state becomes failed, which is a terminal condition, and is created.
If you , then state remains active and the subscription continues billing. But if you , 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 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 has been successfully submitted.
the acquisition is created
Digital River determines that the subscription's is invalid
An invalid is not replaced during the grace period
switches to ended on
