LogoLogo
System Status
2021-12-13
2021-12-13
  • 2021-12-13
  • Charges
    • Charge basics
  • Checkouts
  • Country specifications
  • Customers
  • Events
  • Fees
  • File Links
    • File link basics
  • Files
    • File basics
  • Fulfillments
  • Fulfillment cancellations
  • Fulfillment orders
  • Fulfillment returns
  • Inventory items
  • Inventory levels
  • Invoices
    • Invoice basics
  • Logistics returns
  • Orders
    • Order basics
  • Payouts
  • Plans
    • Plan basics
  • Refunds
  • Reservations
  • Returns
  • Sales summaries
  • Sales transactions
  • Shipments
  • Shipping labels
  • Shipping quotes
  • SKUs
  • SKU Groups
  • Sources
  • Subscriptions
    • Subscription basics
  • Tax identifiers
  • Webhooks
  • Drop-in checkout links
  • Drop-in checkout sessions
    • Checkout-sessions basics
  • Drop-in shipping quotes
  • Store credit callout
Powered by GitBook
On this page
  • Upstream identifier
  • Currency
  • Language
  • Product data
  • Subscription information
  • Strike through price
  • Shopping country
  • Ship from
  • Customer type
  • Auto collect customer type
  • Tax-inclusive
  • Registered customers
  • Customer identifier
  • Saved addresses
  • Shipping methods
  • Store credits
  • Style
  1. Drop-in checkout sessions

Checkout-sessions basics

Gain a better understanding of how to define a checkout-session

PreviousDrop-in checkout sessionsNextDrop-in shipping quotes

Last updated 2 months ago

A determines what information and options are presented to customers in .

At a minimum, your needs to contain and .

You can also tell us whether your prices are .

If the customer’s cart contains , provide for customers to select from.

When checking out , you can send their and .

For complete specifications, refer to the reference docs.

Upstream identifier

In upstreamId, you can pass the unique identifier of the order in your system. If upstreamId is not null, displays its value as the order number during the .

Currency

Language

To control how the checkout experience, purchase invoices, and credit memos are localized, you can pass language in the create checkout-session request.

Product data

For each product in the customer’s cart, you'll need to use items[] to send the:

  • quantity

{
  "currency": "USD",
  "items": [
    {
      "skuId": "3ea112ec-83b6-45c7-8e22-e2114e903745",
      "quantity": 1,
      "price": 300
    }
  ],
  ...
}

You can also use items[] to provide:

  • a discount on the product

Subscription information

curl --location 'https://api.digitalriver.com/drop-in/checkout-sessions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Your secret API key>' \
--header 'Cookie: incap_ses_1534_1638494=XqzQWfBdTnr/Iulkbd1JFRgmMGUAAAAATAFsJGY9H4p0aPzzfZ+ABg==; nlbi_1638494_1914372=rwWKAgHbKVXvxmI9vwbRrQAAAADFueEsAnIupi3c6RgUhNET; visid_incap_1638494=ZgPNr8DiSPety37xbpnVqijUnmQAAAAAQUIPAAAAAAC6uhinP72rh9xkXa7aYFH+' \
--data-raw '{
    ...
    "items": [
        {
            ...
            "subscriptionInfo": {
                "plan": {
                    "interval": "month",
                    "intervalCount": 1
                }
            }
        }
    ],
    ...
}'

Strike through price

curl --location 'https://api.digitalriver.com/drop-in/checkout-sessions' \
...
--data-raw '{
  ...
  "items": [
    {
      ...
      "quantity": 1,
      "price": 100,
      "strikeThroughPrice": 125
    }
  ],
  ...
}

So, if an items[] has a quantity that's greater than 1, and you're trying to communicate a discount, make sure you implement pre-request logic that ensures strikeThroughPrice is less than price multiplied by quantity. Otherwise, the product's price will appear to be marked up instead of discounted.

The parameter is not intended for use with either discount or items[].discount since this might result in conflicting information being displayed in the experience.

Shopping country

curl --location --request POST 'https://api.digitalriver.com/drop-in/checkout-sessions' I am running a few minutes late; my previous meeting is running over.
--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": "jsmith@digitalriver.com",
                "organization": "Digital River"
            },
            {
                "address": {
                    "line1": "62 Trinity Crescent",
                    "line2": "",
                    "city": "WHITCHURCH",
                    "postalCode": "CF4 9ZB",
                    "country": "GB"
                },
                "name": "Brenna Brawner",
                "phone": "07854319925",
                "email": "anna@dr.com",
                "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.

Prebuilt Checkout

Components

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 customers are shown a form that collects their tax identification number and whether they have the option to enter a value or are required to do so.

  • The options are displayed in the payment collection stage.

Ship from

To get this data added to the checkout-session, you can:

Customer type

If customerType is business, customers must enter their company's name in the shipping and billing information collection forms.

Auto collect customer type

For details, refer to:

Tax-inclusive

The taxInclusive boolean determines how we treat product prices when calculating tax.

It also dictates how prices are displayed in the checkout experience. The default value is false. If you set taxInclusive to true, then the experience indicates that the total amount includes VAT.

Registered customers

Customer identifier

To check out customers registered in your system, send their customerId.

{
  ...
  "customerId": "230f61be-8822-4325-9926-e9d0731691b4"
  ...
}

Saved addresses

If you persist registered customers’ addresses, and the customer checking out has one or more saved values 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": "jsmith@digitalriver.com",
        "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": "anna@dr.com",
        "organization": "Digital River",
        "additionalAddressInfo": {
          "neighborhood": "Centro",
          "division": "営業部",
          "phoneticName": "ヤマダ タロ"
        }
      }
    ]
  },
  ...
}

In the address collection stage, we present these saved values to customers for convenience.

For each options.addresses[], Digital River only displays its name and address.

Shipping methods

{
  ...
    "options": {
            "shippingMethods": [
                {
                    "amount": 5,
                    "description": "standard",
                    "serviceLevel": "SG",
                    "deliveryInformation": {
                        "businessDaysInTransit": "3 Business Days",
                        "estimatedArrival": {
                            "date": "2024-05-18T12:00:00",
                            "dayOfWeek": "Saturday"
                        },
                        "pickupDate": "2024-05-16T17:30:00",
                        "weekendService": {
                            "saturdayDelivery": true
                        },
                        "supportCutoffTime": "15:30:00"
                    }
                },
                {
                    "amount": 15,
                    "description": "next day",
                    "serviceLevel": "ND",
                    "deliveryInformation": {
                        "businessDaysInTransit": "1 Business Day",
                        "estimatedArrival": {
                            "date": "2024-05-15T12:00:00",
                            "dayOfWeek": "Thursday"
                        },
                        "pickupDate": "2024-05-16T17:30:00",
                        "weekendService": {
                            "saturdayDelivery": false
                        },
                        "supportCutoffTime": "15:30:00"
                    }
                }
            ]
        ...
      },
      ...
}

Each options.shippingMethods[] requires an amount but not a serviceLevel. However, this data helps Digital River detect fraud, so we highly encourage you to pass it.

400 Bad Request
{
    "type": "bad_request",
    "errors": [
        {
            "code": "invalid_request",
            "message": "Shipping methods are required with physical items"
        }
    ]
}

Store credits

In the payment collection forms, we display amount, name, iconUrl and lastFour to customers.

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

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.

lastFour

The last four digits of the customer's store credit card.

Style

You need to pass currency in your . This value determines how amounts are denominated in the checkout experience.

For a list of accepted values, refer to .

If you define in the , that value gets assigned to the language.

Digital River uses the language to set the language, determining once the is successfully created.

skuId or productDetails. For details, refer to .

price or aggregatePrice. For details, refer to .

.

a location.

a that highlights how much customers are saving

If you're using an external subscription service and would like the billing frequency of the subscription that the customer is acquiring to be displayed in the checkout experience, then specify a plan.interval and plan.intervalCount in items[].subscriptionInfo of your create.

For details on configuring a for use with , refer to .

Digital River reads those values and displays them in the order summary section of .

This feature is not yet supported in .

Additionally, if you need this data to populate or some other potential use case, then we also add these key-value pairs to the with a of .

To highlight how much customers are saving when purchasing a product, you can send items[].strikeThroughPrice. The value you assign this parameter in a request typically represents the original, pre-discounted price of an items[], which Digital River then crosses out and displays next to the discounted price.

The currently doesn't support this feature.

Other parameters in the request don't affect how strikeThroughPrice is rendered in the checkout experience. Digital River displays its value as is. For example, we don't adjust it depending on the setting.

If you're using the , then we perform a currency conversion on strikeThroughPrice, just like we do with price, based on what when they initiate checkout.

A shoppingCountry represents the country in which a customer is based.

If you send a shoppingCountry that's not null, Digital River uses that value to populate the shipTo.address.country. This is true whether represents .

You can also . If you do so, shoppingCountry in a overrides (but doesn't overwrite) the value saved in the Digital River Dashboard.

Additionally, shoppingCountry prompts Digital River to disable the shipping country drop-down menu and blocks customers from selecting any whose country doesn't match shoppingCountry.

However, a shoppingCountry and billTo.address.country don't need to match. As a result, the bill to country drop-down menu remains operable, and customers can choose from any .

The following passes shoppingCountry , and its single reference a .

And even though only references , the and order.* contain shipTo.address.country.

What a customer's inputs are subjected to.

The designated affects what compliance disclosures are displayed and whether a is eventually generated.

If contains , then your needs to meet certain shipFrom.address requirements.

Refer to on the page for details. There, you will find requirements, which the checkout-session wraps.

Send shipFrom in a .

. If you do this, then any shipFrom values sent in a override (but don't overwrite) those saved in the Digital River Dashboard.

to dynamically provide Digital River with one or more shipFrom locations during the checkout process.

The customerType indicates whether customers are purchasing an individual or on behalf of a business.

In many cases, a value of business is required to activate the tax identifier collection form. For details, refer to .

You can pass in a . But to do so, you'll need to have this information before initiating checkout.

If you'd like Digital River to ask customers during the checkout process whether they're purchasing on behalf of a business, then you'll need to , and your must (1) omit customerType (2) or assign a value of individual or null to this parameter.

in the on the page

on the page.

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

Digital River uses this value to determine whether a with that identifier exists in our system.

If it does, we retrieve that transaction-applicable [] and payment and, for convenience purposes, present them as options in the tax identifier and payment collection forms.

If the doesn’t yet exist in our system, we create a new object and assign it the customerId you provided.

In either case, as registered customers progress through a , they can save their shipping information, tax identifiers, and billing information for future transactions. They can also do the same for their selected payment method in and .

If contain , you must provide Digital River shipping options for customers to select from. You can do this in one of the following ways:

First, you can send options.shippingMethods[] in the .

Alternatively, you can . These represent static options (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 overrides your saved values in the Digital River Dashboard.

Finally, you can River calls at checkout time. This lets you offer your customers dynamic options in the shipping method selection stage. The data returned by this endpoint overrides any options.shippingMethods[] sent in your request or saved in the Digital River Dashboard.

For each of the options.shippingMethods[], the user is displayed its amount, description, and , as well as businessDaysInTransit, estimatedArrival.date, and estimatedArrival.dayOfWeek in deliveryInformation.

If you submit a with physical but without options.shippingMethods[], and you don't have or a shipping saved in Digital River Dashboard, then the request returns the following error:

The options allows you to pass one or more storeCredits[]. Each element in this array can be defined by an , , , , and .

For more details, refer to .

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

You can control the appearance and visual behavior of a by defining style in a .

For details, refer to .

checkout-session's
checkout-session's
customer
customer
subscriptionInfo
shipFrom
strikeThroughPrice
taxInclusive
options.addresses[]
checkout-session's
options.addresses[]
A customer identifier
Saved addresses
checkout-session
checkout-sessions API
currency
product data
tax-inclusive
shipping method options
registered customers
unique identifiers
saved addresses
checkout-session's
checkout-session's
checkout's
order
checkout-session
checkout-session's
items[]
checkout-session
items[]
checkout
POST /drop-in/checkout-sessions
customer's
checkout-session's
event
items[].skuId
items[]
customerType
items[]
items[]
amount
name
upstreamId
iconUrl
lastFour
create checkout-session request
checkout-session request
create checkout-session
create checkout-session request
create checkout-session request
create checkout-session request
create checkout-session request
create checkout-session request
create checkout-session request
POST /drop-in/checkout-sessions
create checkout-session request
POST /drop-in/checkout-sessions
POST /drop-in/checkout-sessions
create checkout-session request
options.language
Prebuilt Checkout's configuration object
how purchase invoices and credit memos are localized
Product basics
Setting product price
Digital River's subscription service
Processing subscription acquisitions
Prebuilt Checkout
Components
email notifications
type
checkout_session.order.created
order summary component
local pricing service
users have selected
physical, digital, or mixed goods
save a default shopping country in Digital River Dashboard
digital product
digital products
checkout_session.order.created
events
address validations
selling entity
purchase invoice
physical products
Ship from requirements
Providing address information
Save a default ship-from address in the Digital River Dashboard
Use a shipping endpoint
Supported tax identifiers
turn on this feature in Digital River Dashboard
B2B transactions
Name and address stage
Prebuilt Checkout
Business to business transactions
Address Component
taxIdentifiers
sources[]
Prebuilt Checkout
Prebuilt Checkout
Components
physical products
save default shipping methods in the Digital River Dashboard
create checkout-session request
set up a shipping endpoint that Digital
default shipping methods
callout endpoint
Offering store credit
Prebuilt Checkout
Defining experience
Supported languages
shippingTerms
error
low-code checkouts
physical products
Prebuilt Checkout
thank you stage