Set Up Callbacks for BigCommerce
Learn how to set up checkout callbacks for BigCommerce.
Bolt provides optional callbacks during the checkout process that can be used to trigger frontend analytics events. In our BigCommerce integration, callbacks should be defined in the same template file in which Bolt’s connect script is added.
How it Works
After connect-bigcommerce.js executes, a BoltCheckout object is available in global scope. window.BoltCheckout.setClientCustomCallbacks(callbacks) is a function with a single object argument with the following properties: check, onCheckoutStart, onEmailEnter, onShippingDetailsComplete, onShippingOptionsComplete, onPaymentSubmit, success, and close.
setClientCustomCallbacks() cannot be called until BoltCheckout is initialized during the execution of Bolt’s connect script. You should delay the execution using a setInterval method below:
<script>
var callbacks = {
check : function () {
// Executes just before the checkout form loads.
// Must return a boolean that will determine if Bolt should proceed with checkout.
return true;
},
onCheckoutStart : function () {
// Executes after the checkout form is presented to the user
},
onEmailEnter: function (email) {
// Executes after the user enters their email address.
},
onShippingDetailsComplete: function (address) {
// Executes when the user proceeds to the shipping options page.
// This is applicable only to multi-step checkout.
// When available the first parameter will contain a user's name and address info.
},
onShippingOptionsComplete: function () {
// Executes when the user proceeds to the payment details page.
// This is applicable only to multi-step checkout.
},
onPaymentSubmit: function () {
// Executes after the user clicks the pay button.
},
success: function (transaction, callback) {
// Executes when the Bolt checkout transaction is successful.
// **IMPORTANT** callback() must be executed at the end of the success function
callback()
},
close: function () {
// This function is called when the Bolt checkout modal is closed.
// This will not be called when create_order endpoint returns a valid URL
// and authorization is successful
}
}
var setupCallbacks = setInterval(function() {
if (typeof(BoltCheckout) != 'undefined') {
clearInterval(setupCallbacks);
window.BoltCheckout.setClientCustomCallbacks(callbacks)
}
}, 100);
</script>
Example Successful Callback Response
success: function(transaction, callback) {
{
"id": "TAiv8ncw4bNTB",
"type": "cc_payment",
"processor": "vantiv",
"date": 1663087484404,
"reference": "H3DQ-HDBL-ABCD",
"status": "pending",
"from_consumer": {
"id": "CAfmR5Vfz7eaD",
"first_name": "Testy",
"last_name": "McTest",
"phones": [{
"id": "",
"number": "15595555555",
"country_code": "1",
"status": "",
"priority": ""
}],
"emails": [{
"id": "",
"address": "example@gmail.com",
"status": "",
"priority": ""
}],
"email_verified": false,
"platform_account_status": "none"
},
"to_consumer": {
"id": "CAhPBSfsSc7re",
"first_name": "Fred",
"last_name": "Butson",
"email_verified": false,
"platform_account_status": "none"
},
"from_credit_card": {
"id": "CA4egedZdWrJU",
"last4": "1111",
"bin": "411111",
"expiration": 2014416000000,
"network": "visa",
"token_type": "bolt",
"priority": "listed",
"display_network": "Visa",
"icon_asset_path": "img/issuer-logos/visa.png",
"status": "active",
"billing_address": {
"id": "AA4ytf5s1jR4B",
"street_address1": "123 address Ave",
"street_address2": "",
"locality": "City",
"region": "California",
"postal_code": "90210",
"company": "",
"country": "United States",
"country_code": "US",
"first_name": "Testy",
"last_name": "McTest",
"name": "Testy McTest",
"phone": "15595555555",
"email": "example@gmail.com",
"priority": "listed"
}
},
"amount": {
"amount": 38877,
"currency": "USD",
"currency_symbol": "$"
},
"authorization": {
"auth": "84077848320340361",
"reason": "none",
"status": "succeeded"
},
"captures": null,
"merchant_division": {
"id": "MAjBiJMf5jZ6a",
"merchant_id": "MAh47V9jbjabc",
"public_id": "s44ASi1Gl4DE",
"description": "Sandbox",
"display_name": "Sandbox",
"logo": {
"domain": "img-sandbox.bolt.com",
"resource": "test-logo.png"
},
"platform": "woo_commerce",
"hook_url": "https://staging:SC55TCj8Cfws@staging.my-sandbox.com/wp-json/bolt/response",
"hook_type": "bolt",
"is_universal_merchant_api": false,
"is_webhooks_v2": false,
"shipping_and_tax_url": "https://staging:SC55TCj8Cfws@staging.my-sandbox.com/wp-json/bolt/shippingtax",
"shipping_url": "",
"tax_url": "",
"create_order_url": "https://staging:SC55TCj8Cfws@staging.my-sandbox.com/wp-json/bolt/create-order",
"update_cart_url": "https://staging:SC55TCj8Cfws@staging.my-sandbox.com/wp-json/bolt/update-cart",
"confirmation_redirect_url": ""
},
"transaction_properties": {
"avs_result": "00",
"cvv_result": ""
},
"indemnification_decision": "not_indemnified",
"indemnification_reason": "external_review",
"risk_score": 0,
"review_ticket": null,
"billing_address": {
"street_address1": "123 N Chaparral Ln",
"street_address2": "",
"locality": "City",
"region": "California",
"postal_code": "90210",
"company": "",
"country": "United States",
"country_code": "US",
"first_name": "Testy",
"last_name": "McTest",
"name": "Testy McTest",
"phone": "5595555555",
"email": "example@gmail.com",
"priority": "listed"
},
"shipping_address": {
"street_address1": "123 address Ave",
"street_address2": "",
"locality": "City",
"region": "California",
"postal_code": "90210",
"company": "Test Company",
"country": "United States",
"country_code": "US",
"first_name": "Testy",
"last_name": "McTest",
"name": "Testy McTest",
"phone": "5595555555",
"email": "example@gmail.com",
"priority": "listed"
},
"cart": {
"order_reference": "BLT6320b0ff5cfa1",
"discounts": []
},
"user_note": "",
"custom_field_responses": [],
"shipping_option": {
"valid": true,
"value": {
"cost": {
"amount": 0,
"currency": "USD",
"currency_symbol": "$"
},
"reference": "free_shipping:2",
"service": "Free shipping",
"signature": "feU0ANdrOhwIgJAMEpqnPdY3CyjABCby9+M2sjWnJm4=",
"default": true,
"type": "door_delivery",
"tax_amount": {
"amount": 0,
"currency": "USD",
"currency_symbol": "$"
}
}
}
}
// **IMPORTANT** callback() must be executed at the end of the success function
callback();
}
Considerations
- Callbacks are executed from your storefront domain, not Bolt’s IFrame
success()is the only required function; it must invoke thecallback()method after completing custom code.- If redirecting to an order confirmation page, consider adding code to the close function, which checks if an order was completed.