Merchant Callbacks
Choose and implement the synchronous callbacks Bolt Checkout needs from your backend.
Merchant Callbacks let Bolt ask your backend for information while checkout is in progress. Use this page to choose the events your Custom Cart flow needs, then implement each event against its reference schema.
These are synchronous checkout requests. They are different from transaction webhooks, which notify your backend about transaction changes asynchronously.
Generated server SDKs do not implement these inbound handlers. Your application must verify each request and return data from your cart, shipping, tax, discount, or order system. The Python SDK can register the handler URLs in the next server-integration task.
Choose the events you need
| Event | Job | Use it when |
|---|---|---|
order.create | Create or validate the order in your system before authorization | Your backend creates the merchant order during Bolt checkout |
order.shipping | Return shipping options | Checkout needs delivery choices from your backend |
order.tax | Return tax after a shipping choice | Your backend calculates tax separately from shipping |
order.shipping_and_tax | Return shipping and tax together | Your division exposes the combined callback |
discounts.code.apply | Validate a discount and return its value | Checkout accepts merchant discount codes |
For delivery, implement either the separate shipping and tax events or the combined event exposed for your division. Do not implement both paths unless your Bolt configuration requires both.
Implement the callback surface
- Read Merchant Callback conventions for the shared request envelope, response envelope, amount formats, failure behavior, and HMAC verification.
- Implement the events selected above using each event's request and response schema.
- Verify
X-Bolt-Hmac-Sha256against the raw request body before parsing it. - Return HTTP 200 with the matching
{ event, status, data }envelope. - Expose the endpoints over public HTTPS so Bolt can reach them.
- Register the callback URLs for the same division as your publishable key.
If you use one Universal API URL, route each request using its top-level event value. If you use separate URLs, each handler still receives and returns the same envelope.
Test the callbacks
Run a sandbox checkout and confirm the events needed for your cart arrive:
- Enter a shipping address and confirm the expected shipping or combined event returns the available delivery choices.
- Select a delivery choice and confirm tax and the displayed total update correctly.
- Apply a discount, if supported, and confirm the response changes the cart as expected.
- Submit payment and confirm
order.createreaches your server when that event is part of your flow.
Log the event name, response status, and latency during testing. Do not log signing secrets or sensitive shopper data.
Use Custom Cart troubleshooting if checkout does not receive the expected response.