Plugin Events

Events are defined points of significance in the Bold Checkout experience. When a plugin is subscribed to receive an event, Bold Checkout sends an HTTP POST request to the plugin every time someone reaches the trigger for that event.

This page includes details about the event dispatch URL and the various events your plugin can subscribe to.

To learn more about plugin behavior, refer to the conceptual Plugins page.

Receiving events

When an event occurs that your plugin is subscribed to, Bold Checkout sends an HTTP POST request to your event dispatch URL. You provided this URL when completing the plugin intake form.

Event request body

The event request body contains cart, metadata, customer, and order information. The format of the request body is the same for every event; however, depending on the event, all values may not be populated.

The following snippet shows an example of an app_hook request body:

{
  "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": "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": "800-555-0100"
    },
    "addresses": []
  },
  "order_id": 145,
  "properties": {
    "hook": "add_payment"
  },
  "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,
    "payments": [
      {
        "value": 1500,
        "lineText": "Loyalty Points",
        "payment_gateway": "Loyalty Points Program",
        "public_payment_id": "2QK1WLypfKcZNgwmWL6rLe0DOXnOiEj9PpjhvFMfpxyqnLwPh1ue1iD8cuJJUcJr",
        "status": "awaitingPreAuth",
        "currency": "CAD",
        "expiry": "08/2025",
        "avs_result": "M",
        "cvd_result": "M"
      }
    ],
    "payments_total": 1500,
    "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"
}

Events

The following table shows all events that are available to Bold Checkout plugins and when they are triggered during the checkout process.

Event	Description
amend_order	Triggered by a call to the Process Order endpoint. This event triggers only if the order was set to be amendable, either via the Bold Checkout admin or via the plugin.
app_hook	Triggered by a call to the Dispatch App Hook Event endpoint. This event specifies a hook in the event request body's properties. The hook value will correspond to the hook in the call to the Dispatch App Hook Event endpoint.
billing_address_changed	Triggered by the change_billing_address plugin action and the change_shipping_address plugin action when its update_billing field is set to true.
discount_code_added	Triggered by a call to the Add Discount Code endpoint.
discount_code_removed	Triggered by a call to the Delete Discount Code endpoint.
initialize_app	Triggered by a call to the Initialize Order endpoint. Occurs once per full page load during checkout.
initialize_checkout	Triggered by a call to the Initialize Order endpoint.
initialize_currency	Triggered by a call to the Initialize Order endpoint. When using Multi-Currency, this event indicates when currency is initialized. Note that this is before currency changes the prices in Checkout.
item_added	Triggered by a call to the Add Line Item endpoint.
item_updated	Triggered by a call to the Update Line Item endpoint.
item_removed	Triggered by a call to the Delete Line Item endpoint.
order_submitted	Triggered by a call to the Process Order endpoint. Occurs right before an order is submitted for pre-authorization and payment has not yet been captured.
payments_preauthorized	Triggered by a call to the Process Order endpoint. Occurs after payments have been preauthorized, and before the order_submitted event.
received_shipping_lines	Triggered by a call to the List Shipping Lines endpoint. Occurs when one or more valid shipping lines have been found.
shipping_address_changed	Triggered by the change_shipping_address plugin action.
validating_shipping_lines	Triggered by a call to the Set Shipping Line endpoint.