Links

Checkout-sessions

Learn how to define a checkout-session for Drop-in Checkout
A checkout-session determines what information and options are presented to customers in the checkout modal.
At a minimum, your create checkout-session request needs to contain currency and product data. You may also want to tell us whether your prices are tax inclusive. When checking out registered customers, send their unique identifier and (optionally) their saved addresses. If the customer’s cart contains physical products, make sure you're set up to display shipping method options.
For complete request specifications, refer to the checkout-sessions reference documentation.

Currency

A currency is required and the value you pass determines how amounts are denominated in the checkout modal.

Product data

For each product in the customer’s cart, use items[] to send:
{
"currency": "USD",
"items": [
{
"skuId": "3ea112ec-83b6-45c7-8e22-e2114e903745",
"quantity": 1,
"price": 300
}
],
...
}

Shopping country

The shoppingCountry represents the country in which a customer is based.
You can also set a default shopping country in Dashboard. If you do so, the shoppingCountry you send in a POST /drop-in/checkout-sessions overrides the Dashboard setting.
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.
Additionally, passing shoppingCountry instructs DigitalRiverCheckout.js to disable the modal's shipping/delivery country drop-down menu and block customers from selecting any options.addresses[] whose country doesn't equal shoppingCountry.
There's no requirement however that a checkout-session's shoppingCountry and billTo.address.country have to match, and, as a result, the country drop-down in the billing information collection stage remains operable and customers can choose from any of their saved 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' \
--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.
In the billing information stage, however, the country selector remains operational.
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:

Ship from

If items[] contains physical products, then your checkout-session must contain shipFrom.address.country at the line item-level and/or order-level. For details, refer to Ship from address.
You can directly send shipFrom in a create checkout-session API request.
Alternatively, you can configure a default ship from address in Dashboard. If you do this, then any shipFrom values sent in your POST /drop-in/checkout-sessions override the values stored in Dashboard.

Customer type

The checkout-session's customerType indicates whether customers are making the purchase as an individual or a business entity.
In many cases, a customerType of business is required to activate the tax identifier collection stage. For details, refer to Supported tax identifiers.
If you set customerType to business, then customers must enter a company name during both the shipping and billing information collection stage.
Shipping information
Billing information

Tax inclusive

The taxInclusive boolean dictates how prices are displayed in the checkout modal (the default value is false). If you set taxInclusive to true, then the UI indicates that the total amount includes VAT.
The value you assign taxInclusive also determines how we treat product prices when calculating tax.

Registered customers

For checkouts initiated by a registered customer, your request can include:

Customer identifier

To checkout customers who are registered in your system, send their customerId.
{
...
"customerId": "230f61be-8822-4325-9926-e9d0731691b4"
...
}
We use this identifier to look up the customer in our system.
If the referenced customer exists, we retrieve its transaction-applicable taxIdentifiers[] and payment sources[] and present them as options in the tax identifier collection stage and payment collection stage.
If the customer doesn’t exist in our system, we create a new object and assign it the customerId you provided.
In either case, as registered customers progress through the checkout experience, they are given the option to save their shipping information, tax identifiers, billing information and payment methods for use in future transactions.

Saved addresses

If you persist registered customers’ addresses, and the customer checking out has one or more saved addresses 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": "ヤマダ タロ"
}
}
]
},
"customerId": "230f61be-8822-4325-9926-e9d0731691b4"
}
In the checkout modal’s address collection stage, we present these saved addresses to customers for convenience purposes.
For each element in addresses[], the modal only displays name and address.

Shipping methods

If items[] contain physical products, then you must provide Digital River your shipping methods in one of the following ways.
First, you can send options.shippingMethods[] in the create checkout-session request.
Alternatively, you can configure default shipping methods in Dashboard. These are static shipping amounts (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 API request override (but do not overwrite) any configurations that exist in Dashboard.
Finally, you can configure a shipping method endpoint in Dashboard that Digital River calls at checkout time. We then use the response to offer your customers dynamic options in the shipping method selection stage. The data returned by this endpoint overrides any shipping methods sent in your API request or stored in Dashboard. For details, refer to Using a shipping endpoint.
For each of a checkout-session's options.shippingMethods[], the checkout modal displays its amount and description.
{
...
"options": {
"shippingMethods": [
{
"amount": 5,
"description": "Standard Shipping",
"serviceLevel": "SG"
},
{
"amount": 15,
"description": "Next Day Air",
"serviceLevel": "ND"
}
],
...
},
...
}
Each of a checkout-session's shippingMethods[] requires an amount but does not require a serviceLevel. However, since it helps Digital River detect fraud, we highly encourage you to pass this data.
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"
}
]
}

Store credits

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 stage, we display amount, name, iconUrl and lastFour to the customer.
For more details, refer to Offering store credit.
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"
}
]
}
}'

amount

This required parameter represents how much credit you’re offering the customer.

name

The name of the store credit offering. Omitting name or passing a null value doesn't throw an error but it does mean that particular storeCredits[] won't get displayed in the payment collection stage.

upstreamId

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."
}
]
}

iconUrl

The web address of your store credit logo image.

lastFour

The last four digits of the store credit card you've issued the customer.