Create a test accountSign in to DashboardSystem status
Search…
⌃K
Links

Processing subscription acquisitions

Gain a better understanding of how to use Prebuilt Checkout together with Digital River's subscription service to process acquisitions
If you're pairing Prebuilt Checkout with Digital River's subscription service, this page explains how to process:
Once Digital River converts the checkout-session to an order, you'll also need to activate the subscription, fulfill the goods, and manage renewals. For details on how to handle these, and other processes, refer to the Subscription management page.

Subscription acquisitions

During a standard subscription acquisition, your create checkout-session request must pass subscriptionInfo in items[].
For each items[].subscriptionInfo in the request:
  • Use planId to associate the subscription with a plan. For details, refer to Defining a business model.
  • Include terms. To do this, prior to submitting the create checkout-session request, get the plan that the subscription belong to. From the response, retrieve the plan's terms and pass that value in the request. If you don't pass terms, a 400 Bad Request with a code of missing_parameter is returned.
  • Set autoRenewal to true or omit the value. If you set this parameter to false, a 400 Bad Request with a code of invalid_request is returned.
  • If you don't provide a unique subscriptionId, we generate one for you.
Your request must also pass a customerId and should specify a chargeType of customer_initiated.
In addition, acquisition requests can contain:

Multiple items[] with subscriptionInfo

Your create checkout-session request can contain multiple items[] with subscriptionInfo. However, all these recurring items[] must share the same planId and (if you pass your own value) subscriptionId.
If your request contains multiple items[] with subscriptionInfo and they reference different plans, then the following error is returned:
409 Conflict
{
"type": "conflict",
"errors": [
{
"code": "plan_limit_reached",
"parameter": "planId",
"message": "Only one unique subscription plan can be supported in a checkout"
}
]
}

Mixed subscription and non-subscription items[]

Your create checkout-session request can also contain a mix of items[] with and without subscriptionInfo. This allows you to, for example, process transactions that combine the purchase of a one-time physical product with a recurring digital subscription.
However, as noted in the above section, all the items[] with subscriptionInfo must contain the same planId.

Trial subscription acquisitions

You handle free-trial acquisitions in much the same way as standard subscription acquisitions.
However, in free trials, you must slightly modify your create checkout-session request.
For each trial-based items[] in your request:
  • Pass a price or aggregatePrice of 0.0
  • In its subscriptionInfo:
If your request contains an items[] whose (1) subscriptionInfo.freeTrial is true and its price or aggregatePrice is greater than 0.0 or (2) whose subscriptionInfo.freeTrial is false and its price or aggregatePrice is 0.0, then the following error is thrown:
400 Bad Request
{
"type": "bad_request",
"errors": [
{
"code": "invalid_parameter",
"parameter": "items",
"message": "The value of the Free Trial flag is not consistent with the item price or the aggregate price."
}
]
}
For details on how to process a trial-based subscription after Digital River converts the acquisition checkout-session to an order, refer to Trial subscription management on the Subscription management page.

How Digital River processes your requests

For each items[] with subscriptionInfo you sent in the create checkout-session request, Digital River creates a single subscription, sets its to state to draft and then generates an event with a type of subscription.created.
The event's data.object doesn't contain key subscription attributes such as contractBindingUntil, nextReminderDate, currentPeriodEndDate, and nextInvoiceDate. These are populated after you activate the subscription.
After you create a checkout modal, Digital River presents customers with a localized recurring billing agreement in the payment stage and forces them to accept it before they can submit the order. Additionally, we retrieve the interval and intervalCount of the plan that the subscription belongs to and present this information in the order summary section.
Once the order is submitted, Digital River makes the source reusable by associating it with the customer referenced by the customerId you passed in the request.
To learn more about how to activate subscriptions and handle renewals, refer to the Subscription management page.
​
Previous
Using a shipping endpoint
Next
Offering store credit
Last modified 3d ago