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.
A
currency is required and the value you pass determines how amounts are denominated in the checkout modal.For each product in the customer’s cart, use
items[] to send:- A
quantity
{
"currency": "USD",
"items": [
{
"skuId": "3ea112ec-83b6-45c7-8e22-e2114e903745",
"quantity": 1,
"price": 300
}
],
...
}
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:- Whether the tax identifier collection stage gets activated and, if it is, whether customers have the option to enter a value or are required to do so.
- The designated selling entity, and, as a result, what compliance disclosure are displayed in the modal's footer and whether an invoice is eventually generated.
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. 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. 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
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.For checkouts initiated by a registered customer, your request can include:
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.
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.If
items[] contain physical products, then you must provide Digital River your shipping methods in one of the following ways.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"
}
]
}
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. 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 particular storeCredits[] won't get displayed in the payment collection stage. 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 image.
The last four digits of the store credit card you've issued the customer.
Last modified 7d ago