Subscription basics
Learn more about the subscriptions resource.
Last updated
2021-12-13
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 .
The contractBindingUntil attribute represents the date and time when the subscription's contract expires. It's determined by adding the 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 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 section.
The planId uniquely identifies the that the subscription belongs to.
The price, quantity, and SKU identifier of the subscription's products and services are contained in items[].
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.
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 .
The value is inherited from the acquisition .
The currentPeriodStartDate represents the date and time when the subscription's current billing period began. This value, added to the interval, equals the subscription's .
The currentPeriodEndDate represents the date and time when the subscription's current billing period ends. Subtracting the from this value gives you the subscription's .
The nextInvoiceDate represents the date and time of the next billing attempt. It's when Digital River and attempts to capture payment. The value is determined by subtracting the from the subscription's .
The nextReminderDate is the date and time when Digital River creates an with a of .
Once the acquisition is created, Digital River determines whether the is , and, if it is, creates a subscription whose state is draft.
After you , we determine whether (1) the acquisition exists, (2) its 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 , Digital River retrieves data from the resource and uses it to create a . We then add subscription and to the of an with a of .
On the subscription's , Digital River checks the 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 to open, which initiates the billing process and pushes the subscription's state to activePendingInvoice.
If we immediately capture payment, then the invoice becomes , the subscription transitions to active and is triggered.
If we're unable to synchronously capture payment, then the subscription's state remains activePendingInvoice. This indicates that our is still attempting to collect payment.
The service continues making billing attempts until either (1) payment is successfully captured or (2) the elapses. A successful billing attempt moves the subscription's state to active and triggers the creation of . If the invoice is ultimately , 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 , at which point recurring billing permanently stops.
If we can’t create a 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 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
