Implement the Event-Action Loop
Bold encourages developers to use integrations in order to extend Bold Checkout, instead of plugins. There are two types of integrations: private and public. For more information, refer to Extend Bold Checkout.
The most common way that Bold Checkout interacts with plugins is via the event-action loop.
A Checkout plugin listens for events (defined points of significance in the checkout experience), and the plugin can respond with actions. Bold Checkout executes the actions, which often result in changes to the order.
For more information about the event-action loop, refer to the conceptual Plugins page.
This how-to guide covers how to implement the event-action loop in your own plugin. It includes examples from the Checkout Example Plugin.
Prerequisites
Before you get started, complete the following steps:
- Complete the steps in Getting Started with Plugins.
- Complete the steps in Implement the Plugin Installation Flow.
Listen for events
For each event, Bold Checkout sends a POST
request to your event dispatch URL (which you provided in the plugin intake form). This request contains the following components:
- HTTP signature — which you must use to verify that the request came from Bold Checkout.
- Request body — which contains information about the checkout session depending on the event type. This request body is always in the same format. Depending on at what point in the session the event was triggered, some values are unpopulated. For example, in an
initialize_checkout
event, the request body might not contain customer and shipping data.
For the full list of events, refer to the Plugin Events reference.
Bold sends only the events indicated in the plugin intake form. For a full list of the events that your plugin is registered for, or change which events you want to receive, reach out to [email protected].
The following snippet shows an example of an initialize_checkout
event request body:
Click to expand
{
"cart": {
"total_weight": 0,
"item_count": 2,
"requires_shipping": null,
"bold_cart_id": 145,
"cart_token": "19ef770ca493359fb7cfb955e76e1da9",
"public_token": "b8e310398168cc8824182045cc8cabde750af025",
"attributes": [],
"line_items": [[]],
"subtotal": 2468
},
"cart_params": [],
"customer": {
"core_info": {
"first_name": "Bold",
"last_name": "McBoldstein",
"tags": "Bold",
"public_id": "1h6j893jsdfewwe",
"customer_id": 1234,
"email": "[email protected]",
"billing_type": "same",
"accepts_marketing": false
},
"shipping": {
"first_name": "Bold",
"last_name": "McBoldStein",
"company": "Bold Commerce LTD",
"address": "50 Fultz Blvd",
"address2": "Another line",
"city": "Winnipeg",
"country": "Canada",
"country_code": "CA",
"province": "Manitoba",
"province_code": "MB",
"postal_code": "R3Y 1L6",
"phone": "1 (800) 555-0100"
},
"billing": {
"first_name": "Bold",
"last_name": "McBoldStein",
"company": "Bold Commerce LTD",
"address": "50 Fultz Blvd",
"address2": "Another line",
"city": "Winnipeg",
"country": "Canada",
"country_code": "CA",
"province": "Manitoba",
"province_code": "MB",
"postal_code": "R3Y 1L6",
"phone": "1 (800) 555-0101"
},
"addresses": []
},
"order_id": 145,
"properties": {},
"idempotent_key": null,
"shipping_lines": [],
"tax_lines": [],
"discount_lines": [],
"order": {
"order_source": "cashier",
"order_source_name": "cashier",
"public_order_id": "lakjfoihiuh223u82989vhsinvd0s9f8",
"customer": {
"id": 23,
"public_customer_id": 22345345346,
"platform_customer_id": 23,
"core_info": [],
"shipping_address": [],
"billing_address": []
},
"currency": "SEK",
"exchange_rate": "1.000000000000",
"fees": [
{
"id": "gift-wrap-1",
"value": 150,
"lineText": "Gift wrapping",
"tag": "Fee",
"taxable": false
}
],
"order_total": 2468,
"resumable_url": "https://example.com/order/abc123",
"shipping": [
{
"id": "abc123",
"value": 5000,
"price": 5000,
"lineText": "Express Rate",
"name": "Express Rate",
"code:": "Express Rate",
"source": "",
"tag": "Shipping",
"delivery_date": "",
"delivery_range": "",
"delivery_days": ""
}
],
"note": "",
"note_attributes": [],
"tags": []
},
"language_iso": "fr",
"event": "initialize_checkout"
}
Verify the HTTP signature
Each request you receive from Bold is signed with an HTTP signature. This signature is a string that is encrypted through HMAC, encoded using your client secret as the key. Before you proceed to handle an event, you must verify that the call came from Bold and is secure.
The following code snippet shows an example of signature verification. Bold's example plugin does so in a middleware.js
file:
const httpSignature = require("http-signature");
function verifyRequest(req, res, next) {
try {
const parsed = httpSignature.parseRequest(req);
const result = httpSignature.verifyHMAC(parsed, process.env.CLIENT_SECRET);
if (result === true) {
next();
} else {
res.status(401).end();
}
} catch (e) {
res.status(401).end();
}
}
module.exports = verifyRequest;
Handle requests based on event type
Now that you verified that the request came from Bold, you can proceed to handle the event appropriately. While there are various ways to do so, Bold's example checkout plugin uses a switch statement to determine how to handle the event. The plugin is registered for the initialize_checkout
and order_submitted
events and has different functions for handling each request, as shown in the following code snippet:
router.post("/", (req, res) => {
let actions;
switch (req.body.event) {
case "initialize_checkout":
actions = handleInitializeCheckout(req);
break;
case "order_submitted":
actions = handleOrderSubmitted(req);
break;
default:
actions = [];
}
res.send({
success: true,
actions: actions,
});
});
Respond to the event with an action
For every event sent to a plugin, Bold Checkout expects a response that contains a "success"
value of true
and a list of actions. If you do not want to perform any actions, return an empty array for the "actions"
value.
For the full list of actions and their structures, refer to the Plugin Actions reference.
The following code snippet shows a response body sent to Bold Checkout for an add_line_item_by_platform_variant
action:
{
"success": true,
"actions": [
{
"type": "add_line_item_by_platform_variant",
"data": {
"platform_variant_id": 9153875214378,
"line_item_key": "9153875214378:4853336925a8c06cc1edc0058577aa48",
"quantity": 1,
"properties": {
"gift_wrap": "yes"
},
"price": 1500,
"is_amendment": true
}
}
]
}
Bold Checkout assumes all actions sent by a plugin have been verified beforehand and found legitimate. It is the responsibility of the plugin to make sure an action is not fraudulent before sending the action to Checkout.
Next steps
After completion of these steps, your plugin has successfully implemented the event-action loop. If necessary for your use case, continue to extend the behavior of your plugin.
- Learn how to call the Bold Checkout APIs.
- Register to listen for Checkout webhooks.