Checkout

Jump to section

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('permalink', 'white-shirt')
  .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))
Method Description
generateToken(identifier, data) Gets a new checkout token

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

Important

Checkout tokens can only be used once and expire after 7 days.

Note

Refer to the full response for generating a checkout token here.


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": "California",
      "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": "California",
      "postal_zip_code": "94103",
      "country": "US"
  },
  "payment": {
      "gateway": "stripe",
      "card": {
          "token": "irh98298g49"
      }
  },
  "pay_what_you_want": "149.99"
}).then((response) => console.log(response));
Method Description
capture(token, data) Capture a checkout by its token ID

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}
Important

When using PayPal, the response returned will contain the information required for you to redirect your customer to PayPal in order to complete their transaction. Read more here for required parameters to send when using PayPal, or see here for the PayPal documentation.

Note

Refer to the full response for capturing a checkout here.


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));
Method Description
getToken(token) Gets information about the checkout token
Note

Refer to the full response for getting an existing checkout token here.


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));
Method Description
getLive(token) Gets the current "live" object
Note

Refer to the full response for the live object here.


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));
Method Description
checkPayWhatYouWant(token, data) Checks whether a checkout has "pay what you want" enabled
Note

Refer to the full response for the "Check Pay What You Want" request here.


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));
Method Description
checkDiscount(token, data) Checks whether a discount code is valid
Note

Refer to the full response for the "Check discount code" here.


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));
Method Description
checkShippingOption(token, data) Checks whether a shipping method is valid
Note

Refer to the full response for the "Check Shipping Method here.


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));
Method Description
getShippingOptions(token, data) Gets the available shipping options

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));
Method Description
setTaxZone(identifier, data) Sets the geographic zone for tax calculation
Note

Refer to the full response for setting the tax zone here.

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));
Method Description
localeListCountries() List all countries
Note

Refer to the full response for the "List all countries" request here.


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));
Method Description
localeListSubdivisions() List all subdivisions (states, provinces, or regions)
Note

Refer to the full response for "List all Subdivisions for a Country" request here.


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));
Method Description
localeListShippingCountries(token) List all countries that can be shipped to for a checkout token
Note

Refer to the full response for the "List available shipping countries" request here.

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));
Method Description
localeListShippingSubdivisions(token, countryCode) List all subdivisions/regions/states in a country which can be shipped to for the current checkout.
Note

Refer to the full response for the "List available shipping subdivisions" request here.

Services SDK reference

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