Here you'll find information on how to define and create a Checkout and then use the response from the Checkouts API.
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 |
| Both | Refer to Using the customer identifier​ |
| Both | Refer to Using sources​ ​ |
| Both | Refer to Selecting a currency​ |
| Both | Refer to Applying a customer credit​ |
| Both | The email address of the customer. |
| Both | Refer to Designating a locale |
| Both | An arbitrary string identifier that can be used to track the application type. Unlike metadata, this value is searchable. |
| Both | Refer to Providing the IP address​ |
| Both | Refer to Specifying ship from at the checkout-level and Specifying ship from at the item-level ​ |
| Both | Refer to Ship to address​ |
| Both | Refer to Specifying a shipping choice​ |
| Create | Refer to Checkout level discount​ |
| Both | Refer to Describing the items |
| Create | Refer to Shipping discount​ |
| Create | Refer to Configuring taxes |
| Both | Refer to Initiating a charge |
| Both | Refer to Tax identifiers​ |
| Create | Refer to Setting the customer type​ |
| Both | Refer to Setting the purchase location​ |
| Both | Refer to Providing the upstream identifier​ |
The following create Checkout request specifies all the required and most of the optional parameters contained in the resource:
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}]}'
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.
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.
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.
When you're ready to place an order, pass the Checkout id
downstream to a POST/orders
request.
{"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}
​