Checkout Tutorial
In this tutorial we will be creating a more complex checkout, with variants, shipping options, and tax support. For this tutorial we will be using a dummy Chec account we've already setup, Feel free to replace the api keys and product permalink with your own. We'll also be using the Javascript SDK, but will include the cURL commands where we can for your reference.
What you'll accomplish in this tutorial.
- Setup Commerce.js
- Creating a checkout token for a product
- Creating a checkout form
- Capture an order that has shipping options, variants, and tax enabled.
1. Setup Commerce.js
Install
First let's install the Commerce.js Javascript SDK and authenticate by using the following code
<script type="text/javascript" src="https://cdn.chec.io/v1/commerce.js"></script>
Authenticate
Next, to authenticate and get going, call Commerce.js with your public API key and store it as a variable.
//This is the public API key created for our Chec Dummy Account, we have also turned on the console debugger
var myStore = new Commerce('pk_test_1101361e43dd408534afd852d22f128d0b7aab34d59d6', true);
2. Creating your checkout token
We've already created a test product with the permalink commerce-js-advanced, let's go ahead an create a Checkout Token for it.
Request
$ curl https://api.chec.io/v1/checkouts/commerce-js-advanced?type=permalink \
-H "X-Authorization: pk_test_1101361e43dd408534afd852d22f128d0b7aab34d59d6"
myStore.Checkout.generateToken('commerce-js-advanced', { type: 'permalink' }, function(resp){
//Render Checkout
var token_id = resp.id; //e.g. chkt_959gvxcZ6lnJ7
//...
},
function(error){
//Error handler
}
);
#Todo
#Todo
Response
The checkout token returned should look similar to this.
As you can see the The Checkout Token Object returned by Chec contains a lot of information to help you generate your checkout.
3. Create a checkout form
There are many ways to go about this, but for this tutorial we are going to use javascript.
As you can see in the Checkout Token, we have supplied some useful verb conditionals about the checkout.
"conditionals": {
"is_active": true,
"is_free": false,
"is_pay_what_you_want": false,
"is_preorder": false,
"is_quantity_limited": false,
"is_sold_out": false,
"has_digital_delivery": true,
"has_physical_delivery": true,
"has_images": false,
"has_video": false,
"has_rich_embed": false,
"collects_fullname": true,
"collects_shipping_address": true,
"collects_billing_address": false,
"collects_extrafields": false
},
"is": {
"active": true,
"free": false,
"pay_what_you_want": false,
"preorder": false,
"quantity_limited": false,
"sold_out": false
},
"has": {
"digital_delivery": true,
"physical_delivery": true,
"images": false,
"video": false,
"rich_embed": false
},
"collects": {
"fullname": true,
"shipping_address": true,
"billing_address": false,
"extrafields": false
}
Using these conditionals and looping through the line_item, variants, and shipping options to generate select for a products variant using data from the checkout token.
(This example used jQuery, a full working example of this checkout is available at the bottom of this page)
$(document).ready(function(){
//Create a checkout token for the product with the permalink 'commerce-js-example'.
myStore.Checkout.generateToken('commerce-js-advanced', { type: 'permalink' }, function(resp){
//Store the checkout token id as a global variable
checkout_token_id = resp.id;
//Loop through each variant in the first line item (we only have one product for this checkout)
$.each(resp.line_items[0].variants, function(k, variant) {
//Open select
var variant_html = "<select name=\"line_items["+resp.line_items[0].id+"][variants]["+variant.id+"]\">";
//For each option in this variant create an <option> field
$.each(variant.options, function(k, option) {
//Set the <option> value as this option's id
variant_html += "<option value=\""+option.id+"\">" + option.name + "</option>";
});
//Close the select
variant_html += "</select><br>";
//Append the new <select> in the variants <div>
$('#variants').append(variant.name+': '+variant_html);
});
});
});
4. Capturing the order
Important
We utilize key => value multidimensional arrays 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 related values would be nested under that key.
- Line item's quantity: line_item[{line_item_id}][quantity]
- Line item's variant: line_item[{line_item_id}][variant][{variant_id}] = "{option_id}"
Tax Support
Tax support in Commerce.js is automatic, we calculate tax based on the shipping address submitted, If for whatever reason you're not submiting an address for the customer, you can supply the tax region with these arguments.
tax[ip_address]Required if only using IP address to set tax location. We will set the tax location to the estimated location of this IPtax[country]Required If not using IP address to set tax location. Must be a valid ISO 3166-1 alpha-2 country code (e.g. GB - United Kingdom)tax[region]Required if Canada (CA) or USA (CA) - Must be a valid short code for the region e.g. CA - California or QB - Quebectax[postal_zip_code]Required If Auto US Sales Tax turned on
EU VAT MOSS
If you have EU VAT MOSS enabled, you can use the helper function "Get buyers location from IP", and use this value to set tax[ip_address]
Important If you're working with PayPal, you should send both tax[ip_address] and tax[country] (by asking the buyer to select their tax country from a drop down) - We use both of these for evidence.
Request (with Test Gateway)
For this request we are simply going to the shipping address to calculate the tax for this order.
$ curl https://api.chec.io/v1/checkouts/{checkout_token_id} \
-H "X-Authorization: pk_test_1101361e43dd408534afd852d22f128d0b7aab34d59d6" \
-d line_items[item_7RyWOwmK5nEa2V][quantity]="1" \
-d line_items[item_7RyWOwmK5nEa2V][variants][vrnt_bO6J5apWnVoEjp]="optn_Op1YoVppylXLv9" \
-d line_items[item_7RyWOwmK5nEa2V][variants][vrnt_4WJvlKpg7pwbYV]="optn_zkK6oL99G5Xn0Q" \
-d customer[firstname]="John" \
-d customer[lastname]="Doe" \
-d customer[email]="buyer@email.com" \
-d shipping[name]="John Doe" \
-d shipping[street]="161 Mission St" \
-d shipping[town_city]="San Francisco" \
-d shipping[county_state]="CA" \
-d shipping[postal_zip_code]="94103" \
-d shipping[country]="US" \
-d fulfillment[shipping_method]="ship_1ypbroE658n4ea" \
-d payment[gateway]="test_gateway" \
-d payment[card][number]="4242 4242 4242 4242" \
-d payment[card][expiry_month]="01" \
-d payment[card][expiry_month]="2019" \
-d payment[card][cvc]="123" \
-d payment[card][postal_zip_code]="94107"
myStore.Checkout.capture('{checkout_token_id}',
{
"line_items": {
//Key is the line item id for "Test Product (Advanced)"
"item_7RyWOwmK5nEa2V": {
"quantity": 1,
"variants": {
"vrnt_bO6J5apWnVoEjp": "optn_Op1YoVppylXLv9", //Key is the variant id for "Color", value is the option id for "Blue"
"vrnt_4WJvlKpg7pwbYV": "optn_zkK6oL99G5Xn0Q" //Key is the variant id for "Size", value is the option id for "Small"
}
}
},
"customer": {
"firstname": "John",
"lastname": "Doe",
"email": "buyer@email.com"
},
"shipping": {
"name": "John Doe",
"street": "1161 Mission St",
"town_city": "San Francisco",
"county_state": "CA",
"postal_zip_code": "94103",
"country": "US"
},
"fulfillment": {
"shipping_method": "ship_1ypbroE658n4ea" //The value is thee shipping id for "USPS Ground"
},
"payment": {
"gateway": "test_gateway",
"card": {
"number": "4242 4242 4242 4242",
"expiry_month": "01",
"expiry_year": "2019",
"cvc": "123",
"postal_zip_code": "94107"
}
}
},
function(resp) {
console.log(resp)
},
function(error) {
console.log(error)
}
);
#Todo
#Todo
Response (Receipt)
If successful, The Receipt Object will be returned!
And that's it!