# Merchant Callbacks

> Choose and implement the synchronous callbacks Bolt Checkout needs from your backend.

Source: https://help.boltapp.com/api-reference/merchant-callback/overview

<span id="about" />

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](/custom-cart/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 [#choose-the-events-you-need]

| Event                                                                                               | Job                                                              | Use it when                                                  |
| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------ |
| [`order.create`](/api-reference/merchant-callback-reference/order/order-create)                     | Create or validate the order in your system before authorization | Your backend creates the merchant order during Bolt checkout |
| [`order.shipping`](/api-reference/merchant-callback-reference/order/order-shipping)                 | Return shipping options                                          | Checkout needs delivery choices from your backend            |
| [`order.tax`](/api-reference/merchant-callback-reference/order/order-tax)                           | Return tax after a shipping choice                               | Your backend calculates tax separately from shipping         |
| [`order.shipping_and_tax`](/api-reference/merchant-callback-reference/order/order-shipping-and-tax) | Return shipping and tax together                                 | Your division exposes the combined callback                  |
| [`discounts.code.apply`](/api-reference/merchant-callback-reference/discount/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.

<span id="shipping-api" />

<span id="tax-api" />

<span id="shipping--tax-api" />

<span id="php-example" />

## Implement the callback surface [#implement-the-callback-surface]

1. Read [Merchant Callback conventions](/api-reference/merchant-callback/conventions) for the shared request envelope, response envelope, amount formats, failure behavior, and HMAC verification.
2. Implement the events selected above using each event's request and response schema.
3. Verify `X-Bolt-Hmac-Sha256` against the raw request body before parsing it.
4. Return HTTP 200 with the matching `{ event, status, data }` envelope.
5. Expose the endpoints over public HTTPS so Bolt can reach them.
6. [Register the callback URLs](/platforms/how-to-integrate/set-up-hook-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.

<span id="test-the-endpoint" />

## Test the callbacks [#test-the-callbacks]

Run a sandbox checkout and confirm the events needed for your cart arrive:

1. Enter a shipping address and confirm the expected shipping or combined event returns the available delivery choices.
2. Select a delivery choice and confirm tax and the displayed total update correctly.
3. Apply a discount, if supported, and confirm the response changes the cart as expected.
4. Submit payment and confirm `order.create` reaches 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.

<span id="errors--troubleshooting" />

Use [Custom Cart troubleshooting](/custom-cart/troubleshooting) if checkout does not receive the expected response.

<span id="next" />