Checkout-sessions

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

A checkout-session determines what information and options are presented to customers in low-code checkouts.

At a minimum, your create checkout-session request needs to contain currency and product data.

You can also tell us whether your prices are tax inclusive.

If the customer’s cart contains physical products, make sure to provide shipping method options for customers to select from.

When checking out registered customers, you can send their unique identifier and their saved addresses.

For complete specifications, refer to the checkout-sessions API reference docs.

Upstream identifier

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

Currency

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

Language

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

For a list of accepted values, refer to Supported languages.

If you define options.language in Prebuilt Checkout's configuration object, that value gets assigned to the checkout-session's language.

Digital River uses the checkout-session's language to set the checkout's language, which, once the order is successfully created, determines how purchase invoices and credit memos are localized.

Product data

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

• skuId or productDetails. For details, refer to Product basics.

• price or aggregatePrice. For details, refer to Setting product price.

• quantity

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

You can also use items[] to provide:

• subscriptionInfo.

• a shipFrom location.

• a discount on the product

• a strikeThroughPrice that highlights how much customers are saving

Subscription information

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 checkout-session request.

For details on how to configure a checkout-session for use with Digital River's subscription service, refer to Processing subscription acquisitions.

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
                }
            }
        }
    ],
    ...
}'

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

This feature is not yet supported in Components.

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

Strike through price

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

Create checkout-sessions request

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

Prebuilt Checkout

Components

The order summary component 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 taxInclusive setting.

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, it will appear that the product's price is being 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 getting displayed in the experience.

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

Shopping country

A checkout-session's 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 checkout-session's shipTo.address.country. This is true whether items[] represents physical, digital, or mixed goods.

You can also save a default shopping country in Digital River Dashboard. If you do so, shoppingCountry in a POST /drop-in/checkout-sessions overrides (but doesn't overwrite) the value saved in Dashboard.

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

Prebuilt Checkout

Components

However, a checkout-session's 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 options.addresses[].

POST /drop-in/checkout-sessions

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' 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": "[e-mail]",
                "organization": "Digital River"
            },
            {
                "address": {
                    "line1": "62 Trinity Crescent",
                    "line2": "",
                    "city": "WHITCHURCH",
                    "postalCode": "CF4 9ZB",
                    "country": "GB"
                },
                "name": "Brenna Brawner",
                "phone": "07854319925",
                "email": "[e-mail]",
                "organization": "Digital River"
            }
        ]
    }
}'

Delivery information

As a result, the country drop-down menu in the delivery information stage is locked.

Billing information

In the billing information stage, however, the country selector remains operational.

Prebuilt Checkout

Components

Events

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:

• What address validations a customer's inputs are subjected to.

• 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.

• What options are displayed in the payment collection stage.

• The designated selling entity, which affects what compliance disclosures get displayed and whether a purchase invoice is eventually generated.

Ship from

If items[] contains physical products, then your checkout-session needs to meet certain shipFrom.address requirements.

For details, refer to Ship from requirements on the Providing address information page. There'll you find checkout requirements, which the checkout-session wraps.

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

• Send shipFrom in a create checkout-session request.

• Save a default ship from address in Dashboard. If you do this, then any shipFrom values sent in a POST /drop-in/checkout-sessions override (but don't overwrite) those saved in Dashboard.

• Use a shipping endpoint to dynamically provide Digital River one or more shipFrom locations during the checkout process.

Customer type

The checkout-session's customerType indicates whether customers are making the purchase as an individual or on behalf of a business.

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

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

Auto collect customer type

You can pass customerType in a create checkout-session request. 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 making the purchase on behalf of a business, then you'll need to turn this feature on in Dashboard and your POST /drop-in/checkout-sessions must (1) omit customerType (2) or assign a value of individual or null to this parameter.

For details, refer to:

• B2B transactions in Name and address stage on the Prebuilt Checkout page

• Business to business transactions on the Address Component page.

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

For checkouts initiated by a registered customer, your create checkout-session request can include the following:

• A customer identifier

• Saved addresses

Customer identifier

To checkout customers registered in your system, send their customerId.

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

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

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

If the customer 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 Prebuilt Checkout, they are given the option to save their shipping information, tax identifiers and billing information for use in future transactions. In both Prebuilt Checkout and Components, they can do the same for their selected payment method.

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": "[e-mail]",
        "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": "[e-mail]",
        "organization": "Digital River",
        "additionalAddressInfo": {
          "neighborhood": "Centro",
          "division": "営業部",
          "phoneticName": "ヤマダ タロ"
        }
      }
    ]
  },
  ...
}

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

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

Shipping methods

If items[] contain physical products, 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 create checkout-session request.

Alternatively, you can save default shipping methods in Dashboard. 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 create checkout-session request override (but do not overwrite) your saved values in Dashboard.

Finally, you can set up a shipping endpoint that Digital 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 Dashboard.

For each of the checkout-session's options.shippingMethods[], the checkout experience's shipping choice selection form displays its amount, description, serviceLevel, and shippingTerms.

{
  ...
  "options": {
    "shippingMethods": [
      {
        "amount": 5,
        "description": "Standard Shipping",
        "serviceLevel": "SG"
      },
      {
        "amount": 15,
        "description": "Next Day Air",
        "serviceLevel": "ND"
      }
    ],
    ...
  },
  ...
}

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.

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"
        }
    ]
}

Store credits

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.

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

For more details, refer to Offering store credit.

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

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

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 can control the appearance and visual behavior of a Prebuilt Checkout by defining style in a create checkout-session request.

For details, refer to Defining experience.