Register callback URLs

Register each callback only after its endpoint returns the envelope described in Merchant Callback conventions.

Register callback URLs

1. Sign in to the Bolt Merchant Dashboard for the environment you are testing.
2. Go to Administration > API and find Merchant Callbacks.
3. Select the division used by your publishable key.
4. Select Add Callback, then choose the callback type for the endpoint you implemented.
5. Enter the public HTTPS URL and save it.
6. Repeat for each callback your checkout needs.

The dashboard shows only the callback types enabled for the selected division. If a type you need is missing, ask Bolt to confirm the division's callback configuration.

Choose a registration method

Use one of the methods available for your division:

• Universal Merchant API: Register one URL for every Merchant Callback. Route each request using its top-level event value.
• Individual callbacks: Register a separate URL for Create Order, Shipping, Tax, or another callback type exposed for the division.

In either case, verify the HMAC signature over the raw request body and return the matching { event, status, data } envelope.

Universal API URL

When Universal Merchant API is available, one public HTTPS URL can receive all Merchant Callback events. The public callback API identifies this registration type as universal_merchant_api.

The combined shipping-and-tax URL is different. It is a legacy division setting exposed as Shipping and Tax in the dashboard. The public POST /v1/merchant/callbacks contract does not accept shipping_and_tax, and GET /v1/merchant/callbacks does not return it. Configure and verify that URL in the dashboard.

If your backend uses Python, the beta Bolt Python SDK wraps the standard callback API as configuration.set_merchant_callbacks() and configuration.get_merchant_callbacks(). It cannot configure or retrieve the combined shipping-and-tax URL because that URL is outside the public callback API.

Verify registration

1. Send a test request to each public endpoint and confirm it returns the expected response envelope.
2. Confirm signature verification uses the raw request body and your signing secret.
3. Call GET /v1/merchant/callbacks with the division ID and confirm each standard callback URL appears.
4. For a combined shipping-and-tax URL, confirm the saved value in the dashboard instead.

The prerequisites guide explains how to find the division ID and query the registered callbacks.