Checkout-sessions
Gain a better understanding of how to define a checkout-session
A checkout-session determines what information and options are presented to customers in low-code checkouts.
If the customer’s cart contains physical products, make sure to provide shipping method options for customers to select from.
When checking out registered customers, you can send their unique identifier and their saved addresses.
In
upstreamId
, you can pass the unique identifier of the order in your system. If upstreamId
is not null
, then Prebuilt Checkout displays its value as the order number during the thank you stage.
You need to pass
currency
in your create checkout-session request. This value determines how amounts are denominated in the checkout experience.To control how the checkout experience, purchase invoices, and credit memos are localized, you can pass
language
in create checkout-session requests. If you define
options.language
in Prebuilt Checkout's modal configuration object, that value gets assigned to the checkout-session's language
.Digital River uses the checkout-session's
language
to set the checkout's language
, which, once the order is successfully created, determines how purchase invoices and credit memos are localized. For each product in the customer’s cart, you'll need to use
items[]
to send its:quantity
{
"currency": "USD",
"items": [
{
"skuId": "3ea112ec-83b6-45c7-8e22-e2114e903745",
"quantity": 1,
"price": 300
}
],
...
}
You can also use
items[]
to provide:- product-level
discount
details.
If you send a
shoppingCountry
that's not null
, Digital River uses that value to populate the checkout-session's shipTo.address.country
. This is true whether items[]
represents physical, digital, or mixed goods.You can also save a default shopping country in Dashboard. If you do so,
shoppingCountry
in a POST /drop-in/checkout-sessions
overrides (but doesn't overwrite) the value saved in Dashboard. Additionally,
shoppingCountry
prompts Digital River to disable the shipping country drop-down menu and blocks customers from selecting any options.addresses[]
whose country
doesn't match shoppingCountry
.Prebuilt Checkout
Components


However, a checkout-session's
shoppingCountry
and billTo.address.country
don't need to match. As a result, the bill to country drop-down menu remains operable and customers can choose from any options.addresses[]
. POST /drop-in/checkout-sessions
Delivery information
Billing information
Events
The following create checkout-session request passes
shoppingCountry
and its single items[].skuId
references a digital product.curl --location --request POST 'https://api.digitalriver.com/drop-in/checkout-sessions' I am running a few minutes late; my previous meeting is running over.
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <secret API key>' \
....
"currency": "JPY",
...
"items": [
{
"skuId": "sku-dig-subscription-01",
"quantity": 1,
"price": 459
}
],
"shoppingCountry": "JP",
...
"options": {
...
"addresses": [
{
"address": {
"line1": "10380 Bren Rd W",
"line2": "line 2",
"city": "Minnetonka",
"postalCode": "55129",
"state": "MN",
"country": "US"
},
"name": "John Smith",
"phone": "952-111-1111",
"email": "[email protected]",
"organization": "Digital River"
},
{
"address": {
"line1": "62 Trinity Crescent",
"line2": "",
"city": "WHITCHURCH",
"postalCode": "CF4 9ZB",
"country": "GB"
},
"name": "Brenna Brawner",
"phone": "07854319925",
"email": "[email protected]",
"organization": "Digital River"
}
]
}
}'
As a result, the country drop-down menu in the delivery information stage is locked.

And even though
items[]
only references digital products, the checkout_session.order.created
and order.*
events contain shipTo.address.country
.order.accepted
{
"id": "6ea4f842-0da7-488b-a078-50444df607b6",
"type": "order.accepted",
"data": {
"object": {
"id": "246318070336",
...
"shipTo": {
"address": {
"country": "JP"
}
},
...
"billTo": {
"address": {
"line1": "123 My St",
"city": "Tokyo",
"postalCode": "100-0013",
"country": "JP"
},
...
},
...
"items": [
{
"id": "175174880336",
"skuId": "sku-dig-subscription-01",
...
}
],
...
}
},
...
}
The
shoppingCountry
also plays a role in determining:- Whether customers are shown a form that collects their tax identification number and whether they have the option to enter a value or are required to do so.
- What options are displayed in the payment collection stage.
- The designated selling entity, which affects what compliance disclosures get displayed and whether a purchase invoice is eventually generated.
If
items[]
contains physical products, then your checkout-session needs to have one or more shipFrom.address.country
values. For details on the specific requirements, refer to Ship from address on the Providing address information page.To get this data added to the checkout-session, you can:
- Save a default ship from address in Dashboard. If you do this, then any
shipFrom
values sent in yourPOST /drop-in/checkout-sessions
override (but don't overwrite) those saved in Dashboard. - Use a shipping endpoint to dynamically provide Digital River one or more
shipFrom
locations during the checkout process.
The checkout-session's
customerType
indicates whether customers are making the purchase as an individual
or on behalf of a business
. If
customerType
is business
, then customers must enter their company's name in both the shipping and billing information collection forms. Additionally, in many cases, a value of
business
is required to activate the tax identifier collection form. For details, refer to Supported tax identifiers. You can pass
customerType
in a create checkout-session request. But to do so, you'll need to have this information before initiating checkout.If you'd like Digital River to ask customers during the checkout process whether they're making the purchase on behalf of a business, then you'll need to turn this feature on in Dashboard and your
POST /drop-in/checkout-sessions
must (1) omit customerType
(2) or assign a value of individual
or null
to this parameter.For details, refer to:
The
taxInclusive
boolean determines how we treat product prices when calculating tax.It also dictates how prices are displayed in the checkout experience. The default value is
false
. If you set taxInclusive
to true
, then the checkout experience indicates that the total amount includes VAT.For checkouts initiated by a registered customer, your create checkout-session request can include the following:
To checkout customers registered in your system, send their
customerId
.{
...
"customerId": "230f61be-8822-4325-9926-e9d0731691b4"
...
}
Digital River uses this value to determine whether a customer with that identifier exists in our system.
If it does, we retrieve that customer's transaction-applicable
taxIdentifiers[]
and payment sources[]
and, for convenience purposes, present them as options in the tax identifier and payment collection forms.If the customer doesn’t yet exist in our system, we create a new object and assign it the
customerId
you provided.In either case, as registered customers progress through a Prebuilt Checkout, they are given the option to save their shipping information, tax identifiers and billing information for use in future transactions. In both Prebuilt Checkout and Components, they can do the same for their selected payment method.
If you persist registered customers’ addresses, and the customer checking out has one or more saved values in your system, you can use
options.addresses[]
to send Digital River this data.{
...
...
"options": {
...
"addresses": [
{
"address": {
"line1": "10380 Bren Rd W",
"city": "Minnetonka",
"postalCode": "55129",
"state": "MN",
"country": "US"
},
"name": "John Smith",
"phone": "952-111-1111",
"email": "[email protected]",
"organization": "Digital River",
"additionalAddressInfo": {
"neighborhood": "Centro",
"division": "営業部",
"phoneticName": "ヤマダ タロ"
}
},
{
"address": {
"line1": "62 Trinity Crescent",
"city": "WHITCHURCH",
"postalCode": "CF4 9ZB",
"country": "GB"
},
"name": "Anna Brawner",
"phone": "07854319925",
"email": "[email protected]",
"organization": "Digital River",
"additionalAddressInfo": {
"neighborhood": "Centro",
"division": "営業部",
"phoneticName": "ヤマダ タロ"
}
}
]
},
...
}
In the address collection stage, we present these saved values to customers for convenience purposes.
For each
options.addresses[]
, Digital River only displays its name
and address
.If
items[]
contain physical products, you must provide Digital River shipping options for customers to select from. You can do this in one of the following ways:Alternatively, you can save default shipping methods in Dashboard. These represent static options (i.e., ones whose
amount
and serviceLevel
are not dependent on where the products are being shipped or how much they weigh). If you use this approach, options.shippingMethods[]
sent in the create checkout-session request override (but do not overwrite) your saved values in Dashboard. Finally, you can set up a shipping endpoint that Digital River calls at checkout time. This lets you offer your customers dynamic options in the shipping method selection stage. The data returned by this endpoint overrides any
options.shippingMethods[]
sent in your request or saved in Dashboard. For each of the checkout-session's
options.shippingMethods[]
, the checkout experience's shipping choice selection form displays its amount
, description
, serviceLevel
, and shippingTerms
. {
...
"options": {
"shippingMethods": [
{
"amount": 5,
"description": "Standard Shipping",
"serviceLevel": "SG"
},
{
"amount": 15,
"description": "Next Day Air",
"serviceLevel": "ND"
}
],
...
},
...
}
Each
options.shippingMethods[]
requires an amount
but not a serviceLevel
. However, this data helps Digital River detect fraud, so we highly encourage you to pass it. If you submit a
POST /drop-in/checkout-sessions
with physical items[]
but without options.shippingMethods[]
, and you don't have default shipping methods or a shipping callout endpoint saved in Dashboard, then the request returns the following error:400 Bad Request
{
"type": "bad_request",
"errors": [
{
"code": "invalid_request",
"message": "Shipping methods are required with physical items"
}
]
}
In the create checkout-session request,
options
allows you to pass one or more storeCredits[]
. Each element in this array can be defined by an amount
, name
, upstreamId
, iconUrl
, and lastFour
. In the payment collection forms, we display
amount
, name
, iconUrl
and lastFour
to customers. curl --location --request POST 'https://api.digitalriver.com/drop-in/checkout-sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Secret API key>' \
....
--data-raw '{
...
"options": {
...
"storeCredits": [
{
"amount": 5,
"name": "Acme Inc.",
"upstreamId": "7654-2345-0987-123456",
"iconUrl": "https://acme-inc.com/store-credit-log.png",
"lastFour": "7831"
}
]
}
}'
This required parameter represents how much credit you’re offering the customer.
The name of the store credit offering. Omitting
name
or passing a null
value doesn't throw an error, but it does mean that that particular storeCredits[]
won't get displayed in the payment collection form. This required parameter uniquely identifies the line of credit in your system. Passing multiple
storeCredits[]
that share the same upstreamId
is not allowed.400 Bad Request
{
"type": "bad_request",
"errors": [
{
"code": "invalid_parameter",
"parameter": "options.storeCredits",
"message": "Unique value required for upstreamId."
}
]
}
The web address of your store credit logo.
The last four digits of the customer's store credit card.
Last modified 1mo ago