Configuration endpoints

Use the published Bolt API to read division identifiers and configure callback URLs. Authenticate with your API key:

curl 'https://api-sandbox.boltapp.com/v1/merchant/callbacks?division_id=YOUR_DIVISION_PUBLIC_ID' \
  -H 'X-API-Key: YOUR_API_KEY'

All examples use the sandbox host. The Bolt API OpenAPI spec defines these operations under Configuration, Webhooks, and Testing.

Manage callback URLs

Reads and writes the callback URLs Bolt uses to reach your server and to redirect shoppers.

GET takes division_id (your Division Public ID) as a query parameter and returns {"callback_urls": [{"type": ..., "url": ...}]}.

POST stores or overrides only the URL types present in the request and leaves the rest untouched. All the writes in one request happen in a single transaction. Expected result: HTTP 200 with an empty body.

Accepted type values:

oauth_redirect, oauth_logout, get_account, create_order, universal_merchant_api, shipping, tax, update_cart, debug, remote_api, product_info, support_page, account_page, mobile_app_domain, validate_additional_account_data, terms_of_service, privacy_policy, base_domain, confirmation_redirect.

Combined shipping and tax is not on that list. Bolt keeps that URL on the division itself rather than alongside the other callbacks, so set it from the Merchant Callbacks card in the dashboard. Sending shipping_and_tax to this endpoint returns HTTP 400 with Must provide a valid url value.

The published reference lists HTTP 400 for invalid input, HTTP 403 for authorization errors, and HTTP 422 for POST input-validation failures. Check the required division_id, callback_urls, and each entry's type and url. A division_id that does not exist, or that belongs to another merchant, returns HTTP 404 on both GET and POST, even though the published reference does not list that status.

The dashboard equivalent is the Merchant Callbacks card under Administration > Developers > API. Available callback types depend on the division's platform and integration configuration.

Setting a URL does not enable the corresponding capability. The Universal Merchant API is stricter than that: if the division does not have the feature, POST rejects the request with HTTP 400 and says that universal_merchant_api is not enabled on the division. That check runs before anything is stored, so no other callback URL in the same request is written either. Ask Bolt to enable the feature first.

Read merchant identifiers

Returns your merchant public ID, your signing secret, and every division's public ID and publishable key. Useful for scripting multi-division setups and confirming which key belongs to which division.

curl 'https://api-sandbox.boltapp.com/v1/merchant/identifiers' \
  -H 'X-API-Key: YOUR_API_KEY'

Expected result: HTTP 200 with merchant_id, signing_secret, and merchant_divisions, an array of division_id and publishable_key. Each publishable_key is the full three-part value (merchant ID, division ID, then the key itself) that client SDKs expect. Treat the whole response as a secret: it contains your signing secret.

Sandbox testing helpers

Use these helpers in sandbox:

• POST /v1/testing/shopper/create creates a disposable Bolt shopper account for automated checkout tests. Authenticate with X-API-Key and send the request fields specified in the API reference. X-Publishable-Key is optional: when you send it, the response also includes an oauth_code for the new shopper.
• GET /v1/testing/card_token returns a token for Bolt's universal test card 4111 1111 1111 1004, along with expiry, last4, bin, and network. Per the API reference the token must be used within 15 minutes of creation.

For test card numbers you can type into checkout directly, see Test cards.

Related

• Authentication
• Environments
• Receive webhooks