Checkout Tokens

Checkout tokens need to be generated before you are able to "capture an order". When you generate a checkout token we return the checkout token object which contains everything you should need to generate the checkouts/purchasing experience. e.g. Fields you need to collect, if you should show shipping options, if a discount code is available for any of the items (so you know to show a discount code field) etc...

To generate a checkout token all you need to supply is the permalink or id of the product or the cart id you'd like to generate a checkout for.

Checkout tokens can only be used once and expire after 48 hours

$ curl https://api.chec.io/v1/checkouts/{identifier}?type={identifier_type} \
    -H "X-Authorization: {key}"
Commerce.Checkout.generateToken('{identifier}', '{identifier_type}', function(resp){
  //Render Checkout
  var token_id = resp.id; //e.g. chkt_959gvxcZ6lnJ7
  //...
  },

  function(error){
  //Error handler
  }
);
$token = Commerce\Checkout::generateToken('{identifier}',  ['type' => '{identifier_type}']);
token = Commerce.Checkout.generate_token('{identifier}',  {:type => '{identifier_type}'})

Helpers

We created Commerce.js to handle all common eCommerce logic. Helper functions help you make common eCommerce calls during the checkout.

For example...

  • Checking if a requested variant, quantity, or shipping option is available
  • Checking if an entered "Pay What You Want" amount or discount code is valid
  • Retrieving running totals for a checkout (i.e. subtotals, shipping totals, & grand totals) - The live object
  • Generate client side validation rules for jQuery
  • Get a full list of states/provinces for a country to populate a <select>
  • Get the buyers location from an ip address
  • Set a new tax zone for the checkout when the customer changes their shipping address

All helper endpoints on the Checkout resource update the Live Object e.g. If you select a variant that is available or a quantity that is available, the live object will be adjusted to reflect this. Most responses contain a "live" object which gives you the live running totals and other information relevant to the current checkout session so you can update displayed totals (and more) straight away.

Helper functions are not required. All totals are recalculated during on capture using the checkout data sent.

#Get the buyers location from their ip (for preselecting address fields or EU VAT MOSS evidence)
$ curl https://api.chec.io/v1/checkouts/{checkout_token_id}/helper/location_from_ip \
    -H "X-Authorization: {key}"

#Example - Is the quantity selected valid?
$ curl https://api.chec.io/v1/checkouts/{checkout_token_id}/check/{line_item_id}/quantity?amount={amount} \
  -H "X-Authorization: {key}"

#Example - Is this order now free? (i.e. after a discount code is entered)
$ curl https://api.chec.io/v1/checkouts/{checkout_token_id}/check/is_free \
  -H "X-Authorization: {key}"

//Get the buyers location from their ip (for preselecting address fields or EU VAT MOSS evidence)
Commerce.Checkout.getLocationFromIP('{checkout_token_id}', function(resp){

});

//Example - Is the quantity selected valid?
Commerce.Checkout.checkQuantity('{checkout_token_id}', '{requested-quantity}', function(resp){

});

//Example - Is this order now free? (i.e. after a discount code is entered)
Commerce.Checkout.isFree('{checkout_token_id}', function(resp){

});
//Get the buyers location from their ip (for preselecting address fields or EU VAT MOSS evidence)
Commerce\Checkout::getLocationFromIP('{checkout_token_id}', ['ip_address' => '{ip_address}']);

//Example - Is the quantity selected valid?
Commerce\Checkout::checkQuantity('{checkout_token_id}', '{line_item_id}', ['amount' => '{amount}']);

//Example - Is this order now free? (i.e. after a discount code is entered)
Commerce\Checkout::isFree('{checkout_token_id}');
#Get the buyers location from their ip (for preselecting address fields or EU VAT MOSS evidence)
Commerce.Checkout.get_location_from_ip('{checkout_token_id}', {:ip_address => "{ip_address}"})

#Example - Is the quantity selected valid?
Commerce.Checkout.check_quantity('{checkout_token_id}', '{line_item_id}', { :amount => '{amount}' })


#Example - Is this order now free? (i.e. after a discount code is entered)
Commerce.Checkout.is_free('{checkout_token_id}')

The Live Object

The live object is a living object which adjusts to show the live tax rates, prices, & totals for a checkout token. Every time a checkout helper endpoint is called this object will be updated to show update information which can be used to help display data back to the customer on the checkout. All checkout helpers that affect price (e.g. check quantity, check variant, check discount etc) with return the live object in its payload.

We create the live object to help you (and us!) display up-to-date totals, tax prices, and other dynamic variables which change during the Checkout process and need to displayed back to the customer. You should use the data in the live object to update the displayed totals on your checkout pages when the customer selects a new variant, enters a discount, or selects a different shipping option.

At Chec we do this on our own checkouts by feeding the live object returned from each helper function into a javascript function which associates the data with the correct element.


Multiple Price Formats

Every price attribute (subtotals, pay what you want minimums, tax totals, etc..) returned from Chec will be an array with 4 formats.

  • raw - No formatting e.g. 49 or 1234.56
  • formatted - Formatted with no currency symbol or code e.g. 49.00 or 1,234.56
  • formatted_with_symbol - Formatted with it's symbol only e.g. $49.00 or £1,234.56
  • formatted_with_code - Formatted with it's currency code only e.g. 49.00 USD or 1,234.56 GBP
{
  "price": {
    "raw": 49,
    "formatted": "49.00",
    "formatted_with_symbol": "$49.00",
    "formatted_with_code": "49.00 USD"
  }
}

Verb Conditionals

We return all conditionals in the conditionals array in most objects. We also return conditionals with their verb as the array key name e.g. is.cart_free or has.physical_delivery or collects.shipping_address.

{
  "conditionals": {
    "collects_fullname": true,
    "collects_shipping_address": false,
    "collects_billing_address": false,
    "has_physical_delivery": false,
    "has_digital_delivery": true,
    "has_available_discounts": false,
    "has_pay_what_you_want": false,
    "collects_extrafields": true,
    "is_cart_free": false
  },
  "collects": {
    "fullname": true,
    "shipping_address": false,
    "billing_address": false,
    "extrafields": true
  },
  "has": {
    "physical_delivery": false,
    "digital_delivery": true,
    "available_discounts": false,
    "pay_what_you_want": false
  },
  "is": {
    "cart_free": false
  }
}

Why? To (hopefully) make your code easier to write, read, and maintain, by nesting variables under their "verb key" your code reads better e.g. checkout.conditionals.is_cart_free vs checkout.is.cart_free - This is particularly nicer to work with for designers who are primarily working with javascript.

It works well for most verb conditionals.


//Few more examples in different syntax
checkout.is.cart_free
$checkout['is']['preorder']
$checkout->is->sold_out

product.has.product_photos
$product['has']['physical_delivery']
$product->has->product_audio

checkout.collects.fullname
$checkout['collects']['billing_address']
$checkout->collects->extra_fields