Managing checkouts

Learn the basics of how to create and update a Checkout.

Here you'll find information on how to define and create a Checkout and then use the response from the Checkouts API.

Defining a checkout

For both POST/checkouts and POST/checkouts/{id} requests, the following table provides the available parameters, whether they are available in a create or update request, and a description of each.

Parameter

Request type availability

Description

customerId

Both

Refer to Using the customer identifier

sourceId

Both

Refer to Using sources

currency

Both

Refer to Selecting a currency

creditAmount

Both

Refer to Applying a customer credit

email

Both

The email address of the customer.

locale

Both

Refer to Designating a locale

applicationId

Both

An arbitrary string identifier that can be used to track the application type. Unlike metadata, this value is searchable.

browserIp

Both

Refer to Providing the IP address

shipFrom

Both

Refer to Specifying ship from at the checkout-level and Specifying ship from at the item-level

shipTo

Both

Refer to Ship to address

shippingChoice

Both

Refer to Specifying a shipping choice

discount

Create

Refer to Checkout level discount

items

Both

Refer to Describing the items

shippingDiscount

Create

Refer to Shipping discount

taxInclusive

Create

Refer to Configuring taxes

chargeType

Both

Refer to Initiating a charge

taxIdentifiers

Both

Refer to Tax identifiers

customerType

Create

Refer to Setting the customer type

purchaseLocation

Both

Refer to Setting the purchase location

upstreamId

Both

Refer to Providing the upstream identifier

Creating the checkout

The following create Checkout request specifies all the required and most of the optional parameters contained in the resource:

cURL
cURL
curl --location --request POST 'https://api.digitalriver.com/checkouts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_key>' \
--data-raw '{
"customerId": 522317440336,
"currency": "USD",
"taxInclusive": false,
"browserIp": "111.111.111.111",
"chargeType": "customer_initiated",
"email": "null@digitalriver.com",
"shipTo": {
"address": {
"line1": "10380 Bren Road West",
"city": "Minnetonka",
"postalCode": "55343 9072",
"state": "MN",
"country": "US"
},
"name": "William Brown"
},
"shipFrom": {
"address": {
"line1": "350 S 5th St.",
"city": "Minneaplis",
"postalCode": "55415",
"state": "MN",
"country": "US"
}
},
"shippingChoice": {
"amount": 5.95,
"description": "USPS: Priority (1 day delivery)",
"serviceLevel": "SG"
},
"items": [
{
"skuId": "bc4aab24-2880-4de7-b6b0-07dd6e6841a9",
"price": 100.00,
"quantity": 2,
"subscriptionInfo": {
"terms": "terms",
"freeTrial": false
}
},
{
"skuId": "e446860d-86a6-4e22-ba38-bbaa2c17de55",
"price": 50.00,
"quantity": 3
}
]
}'

Using the checkout response

Each time you create or update a Checkout, you receive a response from the Checkouts API. The response contains an updated price and tax information at both the checkout and line item level. During the checkout process, you can display these values to your customers so they can review the information.

Additionally, you should update your local platform's data with the values returned in the response. That way you ensure the values in your system stay in sync with those in our system.

Item information

Each element in the items array is returned with a unique identifier. You'll need to use this value when modifying items during the checkout process, creating fulfillments, processing returns, and issuing refunds.

Payment session identifier

Whenever you successfully create a Checkout, we return a payment session identifier. You should pass this value to the configuration object that is used to create an instance of Drop-in.

If, for some reason, you're not using Drop-in to handle payment source creation during checkouts, you can still use the payment session identifier when building your workflows. To do so, you first need to migrate to payment sessions (unless you're already using them). Once you've completed this migration, your integration can pass the payment session identifier to the create source with elements method.

Checkout identifier

When you're ready to place an order, pass the Checkout id downstream to a POST/orders request.

JSON
JSON
{
"id": "180636290336",
"createdTime": "2020-09-16T23:30:35Z",
"customerId": "522317440336",
"currency": "USD",
"email": "null@digitalriver.com",
"shipTo": {
"address": {
"line1": "10380 Bren Road West",
"city": "Minnetonka",
"postalCode": "55343 9072",
"state": "MN",
"country": "US"
},
"name": "William Brown"
},
"shipFrom": {
"address": {
"line1": "350 S 5th St.",
"city": "Minneaplis",
"postalCode": "55415",
"state": "MN",
"country": "US"
}
},
"totalAmount": 382.74,
"subtotal": 355.95,
"totalFees": 0.0,
"totalTax": 26.79,
"totalDuty": 0.0,
"totalDiscount": 0.0,
"totalShipping": 5.95,
"items": [
{
"id": "100442940336",
"skuId": "bc4aab24-2880-4de7-b6b0-07dd6e6841a9",
"amount": 200.0,
"quantity": 2,
"tax": {
"rate": 0.07525,
"amount": 15.05
},
"subscriptionInfo": {
"terms": "terms",
"autoRenewal": false,
"freeTrial": false
},
"availableToRefundAmount": 0.0
},
{
"id": "100442950336",
"skuId": "e446860d-86a6-4e22-ba38-bbaa2c17de55",
"amount": 150.0,
"quantity": 3,
"tax": {
"rate": 0.07525,
"amount": 11.29
},
"availableToRefundAmount": 0.0
}
],
"shippingChoice": {
"amount": 5.95,
"description": "USPS: Priority (1 day delivery)",
"serviceLevel": "SG",
"taxAmount": 0.45
},
"browserIp": "111.111.111.111",
"locale": "en_US",
"customerType": "individual",
"chargeType": "customer_initiated",
"paymentSessionId": "92c65e5b-fe0f-47a1-ae08-9fa681e17362",
"sellingEntity": {
"id": "C5_INC-ENTITY",
"name": "DR globalTech Inc."
},
"sourceId": "b422e538-5d42-4251-b8cb-142552ccf4a4",
"liveMode": false
}