Set up webhooks to notify your backend of events within Bolt. These webhooks can communicate with your OMS or other systems to keep them up to date with Bolt. See our related guide on [Webhooks](https://help.boltapp.com/get-started/during-checkout/webhooks/).
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/bolt-financial-webhooks-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
version: 1.0.1
title: Bolt API Reference Webhooks API
description: "Postman Collection:\n\n[](https://god.gw.postman.com/run-collection/9136127-55d2bde1-a248-473f-95b5-64cfd02fb445?action=collection%2Ffork&collection-url=entityId%3D9136127-55d2bde1-a248-473f-95b5-64cfd02fb445%26entityType%3Dcollection%26workspaceId%3D78beee89-4238-4c5f-bd1f-7e98978744b4#?env%5BBolt%20Sandbox%20Environment%5D=W3sia2V5IjoiYXBpX2Jhc2VfdXJsIiwidmFsdWUiOiJodHRwczovL2FwaS1zYW5kYm94LmJvbHQuY29tIiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InRrX2Jhc2UiLCJ2YWx1ZSI6Imh0dHBzOi8vc2FuZGJveC5ib2x0dGsuY29tIiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImFwaV9rZXkiLCJ2YWx1ZSI6IjxyZXBsYWNlIHdpdGggeW91ciBCb2x0IFNhbmRib3ggQVBJIGtleT4iLCJ0eXBlIjoic2VjcmV0IiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJwdWJsaXNoYWJsZV9rZXkiLCJ2YWx1ZSI6IjxyZXBsYWNlIHdpdGggeW91ciBCb2x0IFNhbmRib3ggcHVibGlzaGFibGUga2V5PiIsInR5cGUiOiJkZWZhdWx0IiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJkaXZpc2lvbl9pZCIsInZhbHVlIjoiPHJlcGxhY2Ugd2l0aCB5b3VyIEJvbHQgU2FuZGJveCBwdWJsaWMgZGl2aXNpb24gSUQ+IiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfV0=)\n\n## About\n A comprehensive Bolt API reference for interacting with Transactions, Orders, Product Catalog, Configuration, Testing, and much more.\n\n Note: You must also reference the [Merchant Callback API](/api-merchant) when building a managed checkout custom cart integration\n"
servers:
- url: https://api.boltapp.com
description: The Production URL (Live Data).
- url: https://api-sandbox.boltapp.com
description: The Sandbox URL (Test Data).
- url: https://api-staging.boltapp.com
description: The Staging URL (Staged Data).
security:
- X-API-Key: []
- OAuth:
- bolt.account.manage
- bolt.account.view
tags:
- name: Webhooks
description: 'Set up webhooks to notify your backend of events within Bolt. These webhooks can communicate with your OMS or other systems to keep them up to date with Bolt. See our related guide on [Webhooks](https://help.boltapp.com/get-started/during-checkout/webhooks/).
'
paths:
/v1/webhooks:
get:
description: Find webhook configurations belonging to a merchant division. Results are limited to only show webhooks authorized by the X-API-Key.
operationId: queryWebhooks
parameters:
- $ref: '#/components/parameters/division_id'
responses:
'200':
content:
application/json:
schema:
properties:
webhooks:
items:
$ref: '#/components/schemas/webhook'
type: array
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/errors_bolt_api_response'
description: BAD REQUEST. Request is malformed or invalid values are detected.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/errors_bolt_api_response'
description: FORBIDDEN. Not authorized to query webhook for this entity.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/errors_bolt_api_response'
description: NOT FOUND. Unable to find webhook.
security:
- X-API-Key: []
summary: Query Webhooks
tags:
- Webhooks
post:
description: 'Create a new webhook to receive notifications from Bolt about various events, such as transaction status. Webhooks must have unique configuration.
**Transaction & account events**:
* `pending` - The payment pre-authorization was successful, and the transaction is now pending fraud review.
* `failed_payment` - The payment failed pre-authorization.
* `payment` - An automatic capture transaction passed authorization and fraud review, and the system captured the funds.
* `auth` - A manual capture transaction passed authorization and fraud review, and you can begin the capture process.
* `rejected_irreversible` - The transaction failed fraud review, with no appeal option available.
* `rejected_reversible` - The transaction was flagged during fraud review; a re-review can be requested.
* `capture` - A manual capture was successful.
* `credit` - The system successfully processed a refund or credit.
* `void` - The system successfully voided the transaction.
* `newsletter_subscription` - The customer subscribed to the merchant''s newsletter.
* `risk_insights` - Information about the transaction''s risk is available from the fraud review.
* `credit_card_deleted` - A customer removed a saved credit card from their account.
**Subscription events**:
* `subscription_created` - A subscription was created from a successful initial transaction.
* `subscription_renewed` - A recurring subscription order was placed successfully and the next order was scheduled.
* `subscription_canceled` - A subscription was canceled, by the merchant, by the shopper, or automatically (e.g. once its dunning retry schedule is exhausted). Also sent alongside `subscription_ended` when the subscription''s configured final dunning action is cancellation.
* `subscription_payment_failed` - A scheduled subscription order''s payment attempt failed.
* `subscription_paused` - A subscription was paused, by the merchant, by the shopper, or automatically once its dunning retry schedule is exhausted (when the configured final dunning action is pausing).
* `subscription_unpaused` - A paused subscription was resumed, by the merchant or by the shopper.
* `subscription_ended` - A subscription was permanently ended after its dunning retry schedule was exhausted. Sent alongside `subscription_canceled` for this case.
'
operationId: createWebhook
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/event_group_create_webhook'
- $ref: '#/components/schemas/events_array_create_webhook'
description: Webhook that receives notifications.
required: true
responses:
'200':
content:
application/json:
schema:
properties:
webhook_id:
$ref: '#/components/schemas/webhook_id'
required:
- webhook_id
type: object
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/errors_bolt_api_response'
description: BAD REQUEST. Request is malformed or invalid values are detected.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/errors_bolt_api_response'
description: FORBIDDEN. Not authorized to create a webhook for this entity.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/errors_bolt_api_response'
description: UNPROCESSABLE ENTITY. Not allowed to receive duplicate notifications. This is to safeguard a webhook listener from receiving duplicate events. Use GET /v1/webhooks and DELETE /v1/webhooks to check for and delete duplicate webhooks.
security:
- X-API-Key: []
summary: Create Bolt Webhook
tags:
- Webhooks
/v1/webhooks/{webhook_id}:
delete:
description: Delete a Bolt webhook. Provide an authorized X-API-Key to perform this action.
operationId: deleteWebhook
parameters:
- description: Webhook ID
in: path
name: webhook_id
required: true
schema:
$ref: '#/components/schemas/webhook_id'
responses:
'200':
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/errors_bolt_api_response'
description: BAD REQUEST. Request is malformed or invalid values are detected.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/errors_bolt_api_response'
description: FORBIDDEN. Not authorized to perform the operation on this resource.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/errors_bolt_api_response'
description: NOT FOUND. Unable to find webhook.
security:
- X-API-Key: []
summary: Delete a Bolt Webhook
tags:
- Webhooks
get:
description: Get Webhook information by its Webhook ID. Results only include webhooks authorized by the X-API-Key.
operationId: getWebhook
parameters:
- description: Webhook ID
in: path
name: webhook_id
required: true
schema:
$ref: '#/components/schemas/webhook_id'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/webhook'
description: Success
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/errors_bolt_api_response'
description: BAD REQUEST. Request is malformed or invalid values are detected.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/errors_bolt_api_response'
description: FORBIDDEN. Not authorized to perform the operation on this resource.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/errors_bolt_api_response'
description: NOT FOUND. Unable to find webhook.
security:
- X-API-Key: []
summary: Get Webhook
tags:
- Webhooks
components:
schemas:
error_bolt_api:
properties:
code:
$ref: '#/components/schemas/code'
message:
$ref: '#/components/schemas/message'
type: object
description: Error object containing custom error information
message:
description: Human-readable description of the error for developers. Should not be shown to users and is not localized.
example: The input is missing a required parameter.
type: string
url:
description: The full URL to receive webhook notifications.
example: https://eva-nerv.shop.com/path/to/hook
type: string
request_result:
description: Custom-defined Bolt result object.
properties:
success:
$ref: '#/components/schemas/request_failed'
type: object
events_array_create_webhook:
allOf:
- $ref: '#/components/schemas/base_create_webhook'
- type: object
properties:
events:
description: 'If `webhook_event_group` is null, pick a list of notification events to subscribe to.
'
items:
$ref: '#/components/schemas/webhooks_type'
type: array
errors_bolt_api:
items:
$ref: '#/components/schemas/error_bolt_api'
type: array
webhook:
properties:
created_at:
description: Webhook creation time in epoch timestamp milliseconds.
example: 1485997169003
type: integer
event_group:
$ref: '#/components/schemas/webhook_event_group'
events:
description: 'All events the webhook is subscribed to. Null when `event_group` = `all`.
'
items:
$ref: '#/components/schemas/webhooks_type'
type:
- array
- 'null'
url:
$ref: '#/components/schemas/url'
webhook_id:
$ref: '#/components/schemas/webhook_id'
required:
- webhook_id
- created_at
- url
type: object
base_create_webhook:
properties:
division_id:
description: The unique ID associated with the specific merchant division.
example: 3X9aPQ67-YrB
type: string
url:
$ref: '#/components/schemas/url'
required:
- division_id
- url
type: object
webhook_id:
description: A unique webhook ID. Reference this value to modify or delete the webhook subscription. operations as well.
example: wh_za7VbYcSQU2zRgGQXQAm-g
type: string
webhook_event_group:
description: 'Subscribe to a group of events.
`all`: subscribe to all existing and future event types
'
enum:
- all
- 'null'
type:
- string
- 'null'
errors_bolt_api_response:
properties:
errors:
$ref: '#/components/schemas/errors_bolt_api'
result:
$ref: '#/components/schemas/request_result'
type: object
code:
description: Custom-defined Bolt error code. This can be used to programmatically react to specific errors.
example: 2001005
format: int64
type: integer
event_group_create_webhook:
allOf:
- $ref: '#/components/schemas/base_create_webhook'
- type: object
properties:
event_group:
$ref: '#/components/schemas/webhook_event_group'
webhooks_type:
description: '[Webhook events](https://help.boltapp.com/developers/guides/webhooks/#transaction-hook-types) that trigger a notification to the URL. **Note**:`newsletter_subscription` is only for merchant use cases.
Subscription events:
* `subscription_created` - A subscription was created from a successful initial transaction.
* `subscription_renewed` - A recurring subscription order was placed successfully and the next order was scheduled.
* `subscription_canceled` - A subscription was canceled, by the merchant, by the shopper, or automatically (e.g. once its dunning retry schedule is exhausted). Also sent alongside `subscription_ended` when the subscription''s configured final dunning action is cancellation.
* `subscription_payment_failed` - A scheduled subscription order''s payment attempt failed.
* `subscription_paused` - A subscription was paused, by the merchant, by the shopper, or automatically once its dunning retry schedule is exhausted (when the configured final dunning action is pausing).
* `subscription_unpaused` - A paused subscription was resumed, by the merchant or by the shopper.
* `subscription_ended` - A subscription was permanently ended after its dunning retry schedule was exhausted. Sent alongside `subscription_canceled` for this case.
'
enum:
- payment
- credit
- capture
- void
- auth
- pending
- rejected_irreversible
- rejected_reversible
- failed_payment
- newsletter_subscription
- risk_insights
- credit_card_deleted
- subscription_created
- subscription_renewed
- subscription_canceled
- subscription_payment_failed
- subscription_paused
- subscription_unpaused
- subscription_ended
example: pending
type: string
request_failed:
example: false
type: boolean
description: Indicates that the request failed. This value is always false.
parameters:
division_id:
description: The unique ID associated to the merchant's Bolt Account division; Merchants can have different divisions to suit multiple use cases (storefronts, pay-by-link, phone order processing). You can view and switch between these divisions from the Bolt Merchant Dashboard.
in: query
name: division_id
required: true
schema:
type: string
securitySchemes:
OAuth:
description: 'Bolt utilizes the OAuth flow that developers can use to attain access to Bolt Account data via APIs.
For all APIs that require authorization, please provide your `access_token` returned from `/v1/oauth/token` via the basic auth bearer header `Authorization: bearer ${TOKEN}`.
[Read more about the OAuth token endpoint.](/api-bolt/#tag/OAuth)
'
flows:
authorizationCode:
authorizationUrl: https://api.boltapp.com/v1/oauth/authorize
refreshUrl: https://api.boltapp.com/v1/oauth/token
scopes:
bolt.account.manage: This scope grants permissions to perform read/edit/delete actions on Bolt Account data
bolt.account.view: This scope grants permissions to perform read only actions on Bolt Account data
openid: This scope grants permissions that enable Bolt SSO by granting an id token JWT that stores account data. Not used in v1/account endpoints
tokenUrl: https://api.boltapp.com/v1/oauth/token
type: oauth2
X-API-Key:
description: Admins and Developers can obtain their Bolt API key from the Bolt Merchant Dashboard.
in: header
name: X-API-Key
type: apiKey