The checkout resource is used to navigate your customers through the transaction and shipping stage of a purchasing flow. A checkout captures data sent from the cart along with the item information, line item IDs, any shipping or billing information as well as tax and shipping rates. The checkout resource is a verbose endpoint that comes with additional helpers eg. Checkout helpers and Services to fully manage your customer's purchasing experience. See here for more high-level concepts on the Checkout resource.

Generate token

The generateToken() method uses GET v1/checkouts/{id} to generate a checkout token which can be used to initiate the process of capturing an order from a cart. generateTokenFrom() gets a new checkout token from a specific identifier type. See below for the example request.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

commerce.checkout.generateToken('white-shirt', { type: 'permalink' })
  .then((checkout) => console.log(checkout.id))

// Gets a new checkout token from a specific identifier type
commerce.checkout.generateTokenFrom('permalink', 'white-shirt')
  .then((checkout) => console.log(checkout.id))

Upon a successful request, a checkout token object will be returned which contains everything you need to create your checkout page.

Capture order

The capture() method uses POST v1/checkouts/{checkout_token_id} to capture an order and payment by providing the checkout token and necessary data for the order to be completed. The resolved promise returns an order object which can be used for receipt.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

commerce.checkout.capture('token', {
  "line_items": {
      "item_7RyWOwmK5nEa2V": {
          "quantity": 1,
          "variants": {
              "vrnt_p6dP5g0M4ln7kA": "optn_DeN1ql93doz3ym"
          }
      }
  },
  "customer": {
      "firstname": "John",
      "lastname": "Doe",
      "email": "john.doe@example.com"
  },
  "shipping": {
      "name": "John Doe",
      "street": "123 Fake St",
      "town_city": "San Francisco",
      "county_state": "US-CA",
      "postal_zip_code": "94103",
      "country": "US"
  },
  "fulfillment": {
      "shipping_method": "ship_7RyWOwmK5nEa2V"
  },
  "billing": {
      "name": "John Doe",
      "street": "234 Fake St",
      "town_city": "San Francisco",
      "county_state": "US-CA",
      "postal_zip_code": "94103",
      "country": "US"
  },
  "payment": {
      "gateway": "stripe",
      "card": {
          "token": "irh98298g49"
      }
  },
  "pay_what_you_want": "149.99"
}).then((response) => console.log(response));

In response to a successful checkout capture, you'll get all the information for the order you need to show a confirmation page to your customer, including the id (the order ID), the customer_reference (customer's order reference), and much more. Note that you may want to store the response in local state since fetching the data again would require a secret key.

Key-value multi-dimensional arrays/objects/hashes are used to immediately associate values with their parent(s) ID when submitting data. For example with line items, the key would be the line_item_id and the related values would be nested under that key.

• Line item's quantity: line_items[{line_item_id}][quantity]
• Line item's variant and selected option: line_items[{line_item_id}][variants][{variant_id}] = {option_id}

Get existing token

The getToken() method uses GET v1/checkouts/tokens/{checkout_token_id} to return an existing checkout token by it's ID. The output from this request will be the same as that of .generateToken().

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

commerce.checkout.getToken('chkt_L5z3kmQpdpkGlA').then((token) => console.log(token));

Checkout helpers

Checkout helper functions are provided to help create custom checkout flows and handle all common commerce logic that would otherwise be complex. Every time a checkout helper endpoint is called, an object called the live object will be updated and the returned data is then typically used to update the checkout UI. All checkout helpers that affect price (e.g. check quantity, check variant, check discount, etc) will return the live object.

Get the live object

The live object is a living object which updates to show the live tax rates, prices, and totals for a checkout token. The getLive() method uses GET v1/checkouts/{checkout_token_id}/live to return the current checkout live object.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce({})

Commerce.checkout.getLive('chkt_L5z3kmQpdpkGlA').then((response) => console.log(response));

Check "Pay What You Want"

If you have enabled "Pay What You Want" pricing, your customers are able to choose the amount they pay. The checkPayWhatYouWant() method uses GET v1/checkouts/{checkout_token_id}/check/pay_what_you_want to validate and saves the desired "Pay What You Want" amount for the provided checkout token, if enabled. If the amount is too low, an invalid response will be returned with the minimum amount required.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

commerce.checkout.checkPayWhatYouWant('chkt_L5z3kmQpdpkGlA', {
  customer_set_price: '100.00',
}).then((response) => console.log(response));

Check discount code

The checkDiscount() method uses GET v1/checkouts/{checkout_token_id}/check/discount?code=ABC123ZYX to validate a discount code for the provided checkout token, and applies it to the order if it is valid.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

commerce.checkout.checkDiscount('chkt_L5z3kmQpdpkGlA', {
  code: 'ABC123ZYX',
}).then((response) => console.log(response));

Check shipping method

The checkShippingOption() method uses GET v1/checkouts/{checkout_token_id}/check/shipping to validate a shipping method for the provided checkout token, and applies it to the order.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

commerce.checkout.checkShippingOption('chkt_L5z3kmQpdpkGlA', {
  shipping_option_id: 'ship_31q0o3e21lDdjR',
  country: 'US',
  region: 'CA',
}).then((response) => console.log(response));

Get shipping methods

The getShippingOptions() method uses GET v1/checkouts/{checkout_token_id}/helper/shipping_options to return a list of available shipping methods for the provided checkout token.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

commerce.checkout.getShippingOptions('chkt_L5z3kmQpdpkGlA', {
  country: 'US',
  region: 'CA',
}).then((response) => console.log(response));

Set tax zone

The setTaxZone() method uses GET v1/checkouts/{checkout_token_id}/helper/set_tax_zone to set the tax zone for the provided checkout token's order, either automatically from a provided IP address, or by the geographic data provided in the request arguments.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

commerce.checkout.setTaxZone('chkt_L5z3kmQpdpkGlA', {
  country: 'US',
  region: 'CA',
  postal_zip_code: '94107',
}).then((response) => console.log(response));

Checkout SDK reference

Refer to the full list of all the available checkout methods here.

Services

The Services endpoint are additional checkout helpers service methods.

List all countries

The localeListCountries() method uses GET v1/services/locale/countries to return a list of all countries registered in the platform. See List available shipping countries for an equivalent list of countries that can be shipped to your account.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

commerce.services.localeListCountries().then((response) => console.log(response));

List all subdivisions for a country

The localeListSubdivisions() method uses GET v1/services/locale/{country_code}/subdivisions to return a list of all subdivisions (states, provinces, or regions) for that country, given a valid country code is provided. See List available shipping subdivisions for country for an equivalent list of subdivisions that can be shipped to for your account.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

const commerce = new Commerce('{your_public_key}');

commerce.services.localeListSubdivisions('US').then((response) => console.log(response));

List available shipping countries

The localeListShippingCountries() method at GET v1/services/locale/{checkout_token_id}/countries returns only the countries which can be shipped to the current checkout.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

Commerce.services.localeListShippingCountries('chkt_L5z3kmQpdpkGlA').then((response) => console.log(response));

List available shipping subdivisions

The localeListShippingSubdivisions() method at GET v1/services/locale/{checkout_token_id}/countries/{country_code}/subdivisions returns only the subdivisions (states, provinces, or regions) in a country which can be shipped to for the current checkout.

Example request using Commerce.js:

import Commerce from '@chec/commerce.js';

Commerce.services.localeListShippingSubdivisions('chkt_L5z3kmQpdpkGlA', 'US').then((response) => console.log(response));

Services SDK reference

Refer to the full list of all the available services methods here.