Building checkouts
Learn the basics of how to sequence the checkout process as well as define, create, update, and use checkouts
Checkouts contain critical data points on a transaction's shipping amount, applicable taxes and fees, discounts, and total cost, that customers need to evaluate before making a purchasing decision.
Your site's checkout experience should contain pages for customers to provide their shipping address, billing address, and payment information. Your site should also have an order review and submission page. Once customers place the order, we recommend you direct them to an order confirmation page.
The Checkouts API allows you to create, retrieve, update and delete individual checkouts, as well as return a list of checkouts. You can also use the API to attach a source to a checkout and detach a source from a checkout.
On this page, you’ll find information on how to:

Sequencing the checkout process

During the initial stages of an ecommerce transaction, customers land on your storefront, review products, build a cart, confirm the cart's details, and initiate checkout. Digital River is typically not involved during these early pre-checkout interactions.
As a result, this section doesn't provide guidance on how to structure these early transaction stages. Instead, it focuses on how to initiate the checkout process. And then, for shopping carts that contain physical products, it explains how to sequence the create and update checkout requests, along with the create and authenticate source requests that you send to Digital River.

Initiating the checkout process

Once customers start adding items to their cart, we recommend you activate a proceed to checkout button. We recommend a similar button on your review cart page. Each button’s click event handler should direct customers to your initial checkout page.

Sending the create checkout request

Once customers click the proceed to checkout button, we recommend that you use your checkout pages to obtain their shipping and billing address. Once customers enter new address information or confirm saved information, retrieve and save that data.
You can then use this saved address data, along with product data in the customer's cart to define items[], shipTo and billTo and then submit the create checkout request.
Since you can’t update a checkout with additional items[] or modify the quantity of existing items[], this sequence reduces the probability that customers will add products to their cart after you submit the create checkout request.
It also provides Digital River the data we need to generate a tax estimate that you can display to the customer.

Displaying compliance disclosures

On all of your checkout pages, typically in the footer, you’re required to display Digital River’s disclosures.
You can use the compliance element to do this. Once the checkout’s sellingEntity.id populates, you should retrieve that value and use it to set compliance.entity in the configuration object of the create compliance element method.
Checkout
Compliance element
Output
{
"id": "e361b5b2-c98c-445d-83d1-870de665b22f",
...
"sellingEntity": {
"id": "C5_INC-ENTITY",
"name": "DR globalTech Inc."
},
...
}
...
var options = {
compliance: {
entity: 'C5_INC-ENTITY'
}
}
...
var compliance = digitalRiver.createElement('compliance', options);
...
This ensures that customers are shown disclosures relevant to the transaction's designated selling entity.
Certain scenarios exist, however, that require you to configure the compliance element with a static, hard-coded selling entity.
For example, when customers initiate checkout, your integration might handle this event by submitting a POST/checkouts that only contains items[] , currency and (potentially) shipFrom. If this is the case, then sellingEntity won’t be populated in the response.
POST/checkouts
201 Created
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
...
--header 'Authorization: Bearer <secret API key>' \
...
--data-raw '{
"currency": "USD",
"items": [
{
"skuId": "7a73ccd7-37ee-42d9-9bc9-fe31e9693c8e",
"quantity": 2,
"price": 10
},
{
"skuId": "902f0b72-1cf2-48ff-acea-7940fc51dd2c",
"quantity": 3,
"price": 5
}
]
}'
{
"id": "e361b5b2-c98c-445d-83d1-870de665b22f",
...
"sellingEntity": {},
...
}
This is because, if a checkout’s items[] contains physical products, Digital River needs shipFrom and shipTo to determine the selling entity. Similarly, if items[] only contains digital products, Digital River needs billTo to make this determination.
For more information about these rules, refer to the Selling entities page.
In this scenario, on your initial checkout page that collects the customer’s shipping and/or billing information, you can use a static selling entity.
But once customers submit their shipping and/or billing information, and you respond by setting the checkout’s shipTo and/or billTo, all of your subsequent checkout pages should contain a compliance element configured with the value contained in sellingEntity.id.
To take another example, if, during the shipping choice selection stage, you call your fulfiller to request shipping quotes, and use the data in their response to set the checkout’s shipFrom, then you won’t be able to dynamically display transaction-specific disclosures on your checkout pages until this operation is complete.

Handling guest and registered customers

If your integration only allows registered checkouts, at some point during the checkout process you'll need to prompt customers to sign in or create an account. When customers create an account, use the Customers API to create a record for them in Digital River’s system.
In registered checkouts, you can use the same API to get a customer and retrieve previously saved shipping information. To expedite the checkout process, you may decide to present this saved shipping address to the customer as an available option.
If you decide to allow guest checkouts, make sure you collect and send us the customer's email address. For more information, refer to address requirements on the Providing address information page.

Handling shipping quotes

If the shopping cart contains physical products, once you have the customer's ship to information, you’ll typically make a shipping quote request to your logistics partner. In most cases, your partner replies with an array of quotes, each containing an eligible shipping method, the shipping method's cost, and one or more ship from addresses.
You should present these quotes to customers and, once they make a selection, send an update checkout request that contains shippingChoice and shipFrom. We can then use this information to generate a more precise tax calculation.
A checkout's shipFrom can be set at either the checkout-level or the line item-level.

Collecting payment

At this stage of the checkout process, you'll need to collect payment information from the customer and use it to either create or authenticate a source.
Before you can do that, however, the payment methods presented to the customer must be applicable to the transaction. With Drop-in payments, you accomplish this by building a configuration object and passing it to the createDropIn() method. If you use DigitalRiver.js with elements, you'll need to configure and invoke retrieveAvailablePaymentMethods().
In registered checkouts, you can use this same method to filter the customer's saved sources by transaction applicability before presenting them to the customer. If the customer selects a saved source from this filtered list, you'll need to use authenticateSource(). This method first determines whether strong customer authentication (SCA) is required and then, if it is, opens a modal window that takes customers through the authentication process.
In both guest and registered checkouts, if customer's decide to provide new payment information, both of our primary source creation methods require a payment session identifier. You can retrieve this session identifier from the checkout.
Both methods also require the customer’s billing address. Unless the customer indicates otherwise, you can use the address you collected earlier in the checkout process.

Applying payment

Once the payment source is successfully created or authenticated, you'll need to apply it to the checkout.
If customers requested that a newly created source be saved to their account, wait until the source is chargeable, verify that it both supportsStorage and is readyForStorage, and then save the source to the customer before attaching the source to the checkout.
If the source is not scheduled for storage, once it's chargeable or pending_funds, you can attach the source to the checkout.
For more information on payments, refer to:

Submitting the order

After you verify that the checkout’s payment session state is valid, activate a place order button on your order review page. As part of handling this button’s click event, convert the checkout to an order.
For more information, refer to the Processing orders page.

Defining a checkout

The following lists some of the key parameters to use when defining checkouts. The table also indicates whether these parameters are available in POST/checkouts and POST/checkouts/{id}, and provides links to additional information on how to use these features. For comprehensive specifications, refer to the Checkouts API reference docs.
Parameter
Request type availability
Documentation
sourceId
Both
currency
Both
creditAmount*
Both
locale
Both
browserIp
Both
shipTo
Both
billTo
Both
shippingChoice
Both
discount
Create
items
Both
shippingDiscount
Create
taxInclusive
Create
chargeType
Both
taxIdentifiers
Both
customerType
Create
purchaseLocation
Both
*The creditAmountparameter is only available in versions 2020-09-30, 2020-12-17, and 2021-02-23
☨ In a POST/checkouts/{id} request, you're restricted to modifying certain line item attributes.

Creating and updating the checkout

To create a checkout, submit a POST/checkouts request. Once you've created the object, and you want to update it, retrieve its unique identifier, and then pass it as a path parameter in a POST/checkouts/{id}.
The following POST/checkouts creates a registered checkout that contains physical products and meets all of our address requirements.
POST/checkouts request
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
...
--data-raw '{
"currency": "USD",
"customerId": 529861350336,
"taxInclusive": false,
"email": "[email protected]",
"shipTo": {
"address": {
"line1": "10380 Bren Road W",
"city": "Minnetonka",
"postalCode": "55343",
"state": "MN",
"country": "US"
},
"name": "John Doe"
},
"shipFrom": {
"address": {
"country": "US"
}
},
"shippingChoice": {
"amount": 5,
"description": "standard",
"serviceLevel": "SG"
},
"items": [
{
"skuId": "6b04ac06-0858-456c-90aa-235772dea9e2",
"quantity": 2,
"price": 10
}
]
}'

Using the checkout

Each time you submit a POST/checkouts or POST/checkouts/{id}, use the data contained in the response to update the data in the upstream commerce platform. This ensures that the values in your system stay in sync with those in ours.
At both the checkout and line item level, the response contains price, tax, landed cost, and fees information. During the checkout process, display this information to customers in your UI.
Checkout
{
...
"totalAmount": 48.4,
"subtotal": 45.0,
"totalFees": 0.0,
"totalTax": 3.4,
"totalImporterTax": 0.0,
"totalDuty": 0.0,
"totalDiscount": 0.0,
"totalShipping": 5.0,
"items": [
{
"id": "4e0afb3e-39d1-4b94-a775-cdce3f521fa1",
"skuId": "0ce492d2-e616-47ac-ad63-6df027577c12",
"amount": 20.0,
"quantity": 2,
"tax": {
"rate": 0.07525,
"amount": 1.51
},
"importerTax": {
"amount": 0.0
},
"duties": {
"amount": 0.0
},
"fees": {
"amount": 0.0,
"taxAmount": 0.0
}
},
...
}
Make sure you save the checkout's unique identifier and unique line item identifiers because they're required when submitting downstream requests. Additionally, the checkout contains payment session details that you use to create payment sources and determine when to submit an order request.

Checkout identifier

Every checkout contains a unique identifier. You can use this identifier to update, retrieve, search for, and delete the checkout. You can also use the identifier to attach a source to the checkout and then, if the customer wants to apply a different payment method, detach the payment source.
When you're ready to convert the checkout to an order, pass this identifier in the body of a POST/orders.
Checkout
{
"id": "f2cd50e5-355d-42d3-8bb7-0c14d8b777e4",
...
}

Item information

Once you create a checkout, Digital River assigns each of its items[] an id. During the checkout process, if you want to modify items you must send these identifiers in POST/checkouts/{id} requests.
Depending on how you send product data in checkouts, each items[] also contains either the skuId or the productDetails object you sent in the POST/checkouts request.
The id of an items[] in a checkout is not the same as the id of the corresponding items[] in the associated order.
Checkout
Order
{
"id": "ec03be84-d684-48a1-b4f4-4dbc05313c93",
...
"items": [
{
"id": "50e69e0a-8e36-4ef9-84a0-45eea7535247",
"skuId": "3a4ad0c5-1640-471e-a6b7-232454474659",
"amount": 20.0,
"quantity": 2,
...
}
],
...
}
{
"id": "227256090336",
...
"items": [
{
"id": "153193900336",
"skuId": "3a4ad0c5-1640-471e-a6b7-232454474659",
"amount": 20.0,
"quantity": 2,
...
}
],
...
"checkoutId": "ec03be84-d684-48a1-b4f4-4dbc05313c93"
}

Payment session

Payment session identifier

In versions 2021-02-23 and lower, you find this identifier in the paymentSessionId attribute. In versions 2021-03-23 and higher, it's contained in payment.session.id.

Payment session information

The checkout's payment.session contains an amountContributed, amountRemainingToBeContributed, and a state. You can use these values to determine when to create an order.
This data is only returned in versions 2021-03-23 and higher.
Checkout
{
"id": "f2cd50e5-355d-42d3-8bb7-0c14d8b777e4",
"createdTime": "2021-03-23T17:34:17Z",
"customerId": "530359580336",
"currency": "USD",
"email": "[email protected]",
"shipTo": {
"address": {
"line1": "10380 Bren Road W",
"city": "Minnetonka",
"postalCode": "55343",
"state": "MN",
"country": "US"
},
"name": "John Doe"
},
"shipFrom": {
"address": {
"country": "US"
}
},
"totalAmount": 26.89,
"subtotal": 25.0,
"totalFees": 0.0,
"totalTax": 1.89,
"totalImporterTax": 0.0,
"totalDuty": 0.0,
"totalDiscount": 0.0,
"totalShipping": 5.0,
"items": [
{
"id": "c9f8d629-e01d-4c89-8c0a-0a0715a07d52",
"skuId": "6b04ac06-0858-456c-90aa-235772dea9e2",
"amount": 20.0,
"quantity": 2,
"tax": {
"rate": 0.07525,
"amount": 1.51
},
"importerTax": {
"amount": 0.0
},
"duties": {
"amount": 0.0
},
"subscriptionInfo": {
"terms": "These are the terms",
"autoRenewal": false,
"freeTrial": false
},
"fees": {
"amount": 0.0,
"taxAmount": 0.0
}
}
],
"shippingChoice": {
"amount": 5.0,
"description": "standard",
"serviceLevel": "SG",
"taxAmount": 0.38
},
"updatedTime": "2021-03-23T17:34:17Z",
"locale": "en_US",
"customerType": "individual",
"sellingEntity": {
"id": "C5_INC-ENTITY",
"name": "DR globalTech Inc."
},
"liveMode": false,
"payment": {
"sources": [
{
"id": "bea8171b-d2bc-44e4-8d7f-1700e65b09ab",
"type": "creditCard",
"amount": 16.89,
"owner": {
"firstName": "William",
"lastName": "Brown",
"email": "[email protected]",
"address": {
"line1": "10380 Bren Rd W",
"city": "Minnetonka",
"postalCode": "55343",
"state": "MN",
"country": "US"
}
},
"creditCard": {
"brand": "Visa",
"expirationMonth": 7,
"expirationYear": 2027,
"lastFourDigits": "1111"
}
},
{
"id": "38818373-7db9-41d9-8895-5667fea13a0b",
"type": "customerCredit",
"amount": 10.0,
"customerCredit": {}
}
],
"session": {
"id": "89bd1d59-1ba0-439f-af96-29230421725c",
"amountContributed": 26.89,
"amountRemainingToBeContributed": 0.0,
"state": "requires_confirmation",
"clientSecret": "89bd1d59-1ba0-439f-af96-29230421725c_5ca86d31-3b21-4d50-b730-9f992b260226"
}
}
}
Copy link
On this page
Sequencing the checkout process
Initiating the checkout process
Sending the create checkout request
Displaying compliance disclosures
Handling guest and registered customers
Handling shipping quotes
Collecting payment
Applying payment
Submitting the order
Defining a checkout
Creating and updating the checkout
Using the checkout
Checkout identifier
Item information
Payment session