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.
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'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.
In addition, acquisition requests can contain:
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"
}
]
}
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
.For each trial-based
items[]
in your 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
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.
To learn more about how to activate subscriptions and handle renewals, refer to the Subscription management page.
Last modified 3d ago