Processing subscription acquisitions
Gain a better understanding of how to use Digital River's subscription service to process acquisitions in Prebuilt Checkout and Components
If you're pairing either of Digital River's low-code checkout solutions with our 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.
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 request, get the plan that the subscription belongs to. From the response, retrieve the plan'sterms
and pass that value in the request. If you don't passterms
, a400 Bad Request
with acode
ofmissing_parameter
is returned. - Set
autoRenewal
totrue
or omit the value. If you set this parameter tofalse
, a400 Bad Request
with acode
ofinvalid_request
is returned. - If you don't provide a unique
subscriptionId
, we generate one for you.
Acquisition requests can also contain:
Your create checkout-session request can contain multiple
items[]
with subscriptionInfo
. However, all these recurring items[]
have to 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"
}
]
}
Your create checkout-session request can also have a mix of
items[]
, some with and some 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.For each trial-based
items[]
in the request:- Pass a
price
oraggregatePrice
of0.0
- In its
subscriptionInfo
:- Set
freeTrial
totrue
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.
For each
items[]
with subscriptionInfo
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. Digital River also presents customers with a localized, recurring billing agreement in the payment collection stage and forces them to accept it before they can submit the order.
Prebuilt Checkout
Payment Component
In Prebuilt Checkout, we retrieve the
interval
and intervalCount
of the plan that the subscription belongs to and present this information in the order summary section.

To make the primary payment
sources[]
reusable, Digital River saves it to the customer referenced by customerId
. To learn more about how to activate subscriptions and handle renewals, refer to the Subscription management page.
Last modified 1mo ago