Frontend events

Each Bolt script reports what the shopper does in its own way. Find the script your page loads:

These run in the shopper's browser. Use them to update your page and to send analytics, not as a record of payment: confirm orders on your server with Merchant Callbacks and webhooks.

Bolt Checkout

Pass callbacks in the third argument of BoltCheckout.configure. Every callback is optional. This example sends checkout start and every notification to a Google Tag Manager data layer:

const callbacks = {
  onCheckoutStart() {
    window.dataLayer?.push({ event: "bolt_checkout_start" });
  },
  onNotify({ eventName, eventSeverity }) {
    window.dataLayer?.push({ event: "bolt_notify", bolt_event: eventName, bolt_severity: eventSeverity });
  },
  success(transaction, callback) {
    // Update your page, then let checkout finish.
    callback();
  },
};

// token is the order token from your backend, as in Web checkout.
BoltCheckout.configure({ orderToken: token }, {}, callbacks);

Where you register callbacks depends on your storefront. The plugin settings cover some callbacks, not all of them.

Callbacks

onNotify events

notifyEvent has an eventName, an eventSeverity of info or error, and, for some events, an eventMetadata object. Bolt adds events over time, so ignore names you don't recognize.

{
  "eventName": "error_invalid_payment",
  "eventSeverity": "error",
  "eventMetadata": { "reasonCode": "payment_declined" }
}

Info events

discountAmount has amount, currency, and currency_symbol, with amount in the currency's minor unit, such as cents. cart is the cart as checkout shows it.

Bolt can turn off info_checkout_transition, info_address_edited, info_checkbox_checked, and info_checkbox_unchecked for a division. If you don't receive them, contact Bolt support.

Error events

SSO sign-in modal

account.js opens Bolt's sign-in modal for SSO Commerce. When a shopper logs in with a verification code, the modal posts window messages to your page as JSON strings. It doesn't call onNotify or any other callback, so listen for message events on window.

Accept messages only from Bolt's sign-in frame: https://connect.boltapp.com in production and https://connect-sandbox.boltapp.com in sandbox. That is not the host that serves account.js, which redirects to account.boltapp.com. If your page loads account.js from a bolt.com host, the frame and its messages use https://connect.bolt.com or https://connect-sandbox.bolt.com instead.

Bolt sends these messages only to pages on your division's Trusted Domains, set in the Merchant Dashboard. A page on any other origin, such as www.example.com when only example.com is listed, receives none.

const BOLT_ORIGIN = "https://connect.boltapp.com";

window.addEventListener("message", (event) => {
  if (event.origin !== BOLT_ORIGIN || typeof event.data !== "string") return;

  let message;
  try {
    message = JSON.parse(event.data);
  } catch {
    return;
  }
  if (message.type !== "onNotify") return;

  const { eventName, eventMetadata } = message.notifyEvent;
  if (eventName === "login_outcome") {
    window.dataLayer?.push({ event: "bolt_sso_login", outcome: eventMetadata.outcome });
  }
});

Each message has this shape:

{
  "type": "onNotify",
  "notifyEvent": {
    "eventName": "login_outcome",
    "eventSeverity": "info",
    "eventMetadata": { "outcome": "SUCCESS" }
  }
}

• One login can send several login_attempted and FAILED events, then at most one SUCCESS or ABANDONED. Nothing follows either of those.
• No outcome is sent when the shopper goes back from the code screen or leaves the page with the modal open, or for a login response that arrives after the modal closed.
• These events cover verification-code login only, not registration, social login, or dashboard login.
• login_attempted carries the shopper's email, and any script on your page can read window messages, so treat it as shopper data. No message carries a verification code or token.

Embedded API

embed.js emits events on the Bolt object when shoppers log in and when Bolt checks their accounts. Call Bolt.initialize first: Bolt.on and Bolt.once throw an error before it.

Bolt.on(eventName: string, callback: (payload: any) => void, options?: { replayLast?: boolean }): () => void;
Bolt.once(eventName: string, callback: (payload: any) => void): () => void;

• Bolt.on calls callback every time the event fires. Bolt.once calls it the next time only.
• Both return a function that removes the listener.
• With replayLast: true, Bolt.on also runs the callback right away with the event's latest payload, if the event already fired on this page. Don't pass replayLast to Bolt.once: when the event already fired, it throws an error instead of running the callback.

Bolt.initialize("YOUR_PUBLISHABLE_KEY");

// Runs on every successful login.
const stopListening = Bolt.on("login_succeeded", ({ result }) => {
  sendAuthorizationCodeToServer(result.authorizationCode); // your function
});

// Runs once, the next time the shopper logs out.
Bolt.once("logout", () => {
  showSignedOutHeader(); // your function
});

// Later, stop listening for logins.
stopListening();

context and loginContext are the context you gave the login modal: checkout, sign_in, register, pre_checkout, or forgot_password.

Events kept for older integrations

These still fire. Use the newer event in new code.

Components report their own events through the component's on method, such as the payment fields' error event and the account checkbox's change event. See Payment fields and Account checkbox.