The v3 generation of the Bolt Embeddable Checkout API, served under a /v3 path with a templated environment server variable. Reorganises the surface around Accounts, Payments (including guest payments), Orders, OAuth, merchant Callbacks, Testing and Events. Bolt gates v3 behind explicit enablement and directs most integrations to v1.
openapi: 3.0.0
info:
version: 3.3.22
title: Bolt API Reference
description: A comprehensive Bolt API reference for interacting with Accounts, Payments,
Orders and more.
termsOfService: https://www.boltapp.com/end-user-terms
contact:
name: Bolt
email: merchantsupport@boltapp.com
url: https://help.boltapp.com/api-bolt/
servers:
- url: https://{environment}.boltapp.com/v3
variables:
environment:
enum:
- api
- api-sandbox
default: api-sandbox
tags:
- name: Account
description: Use the Accounts API to access shoppers' accounts to empower your checkout
and facilitate shoppers' choices.
- name: Payments
description: Use the Payments API to process credit card and alternative payment
methods with Bolt.
- name: Orders
description: Use the Orders API to create and manage orders, including orders that
have been placed outside the Bolt ecosystem.
- name: OAuth
description: Use the OAuth API to enable your ecommerce server to make API calls
on behalf of a Bolt logged-in shopper.
externalDocs:
url: https://help.boltapp.com/products/accounts/direct-api/oauth-guide/
- name: Callbacks
description: Implement Callback endpoints on your servers to power Bolt experiences.
Different Bolt packages require different callbacks to be implemented. Consult
your relevant product documentation for a list of required callbacks.
- name: Testing
description: Use the Testing API to generate and retrieve test data to verify a
subset of flows in non-production environments.
- name: Events
description: Use the Events API to ingest shopper events to enable real-time insights
and actions.
paths:
/account:
get:
summary: Retrieve account details
operationId: accountGet
x-speakeasy-name-override: GetDetails
description: Retrieve a shopper's account details, such as addresses and payment
information. The account's details are filtered to be relevant to your merchant
account, and some fields may be missing for some accounts. See the schema
for details.
tags:
- Account
security:
- oauth:
- bolt.account.manage
- bolt.account.view
api-key: []
parameters:
- $ref: '#/components/parameters/x-publishable-key'
- $ref: '#/components/parameters/x-merchant-client-id'
responses:
'200':
description: The account details were successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/account'
4XX:
$ref: '#/components/responses/response-4xx'
default:
$ref: '#/components/responses/response-default'
/account/addresses:
post:
summary: Add an address
operationId: accountAddressCreate
x-speakeasy-name-override: AddAddress
description: Add an address to the shopper's account
tags:
- Account
security:
- oauth:
- bolt.account.manage
api-key: []
parameters:
- $ref: '#/components/parameters/x-publishable-key'
- $ref: '#/components/parameters/x-merchant-client-id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/address-listing'
examples:
address-all-fields:
$ref: '#/components/examples/address-all-fields'
address-some-fields:
$ref: '#/components/examples/address-some-fields'
responses:
'200':
description: The address was successfully added
content:
application/json:
schema:
$ref: '#/components/schemas/address-listing'
4XX:
$ref: '#/components/responses/response-address-error'
default:
$ref: '#/components/responses/response-default'
/account/addresses/{id}:
put:
summary: Edit an existing address
operationId: accountAddressEdit
x-speakeasy-name-override: UpdateAddress
description: Edit an existing address on the shopper's account. This does not
edit addresses that are already associated with other resources, such as transactions
or shipments.
tags:
- Account
security:
- oauth:
- bolt.account.manage
api-key: []
parameters:
- $ref: '#/components/parameters/x-publishable-key'
- $ref: '#/components/parameters/x-merchant-client-id'
- in: path
name: id
schema:
type: string
example: D4g3h5tBuVYK9
required: true
description: The ID of the address to edit
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/address-listing'
examples:
address-all-fields:
$ref: '#/components/examples/address-all-fields'
address-some-fields:
$ref: '#/components/examples/address-some-fields'
responses:
'200':
description: The address was successfully edited
content:
application/json:
schema:
$ref: '#/components/schemas/address-listing'
4XX:
$ref: '#/components/responses/response-address-error'
default:
$ref: '#/components/responses/response-default'
delete:
summary: Delete an existing address
operationId: accountAddressDelete
x-speakeasy-name-override: DeleteAddress
description: Delete an existing address. Deleting an address does not invalidate
or remove the address from transactions or shipments that are associated with
it.
tags:
- Account
security:
- oauth:
- bolt.account.manage
api-key: []
parameters:
- $ref: '#/components/parameters/x-publishable-key'
- $ref: '#/components/parameters/x-merchant-client-id'
- in: path
name: id
schema:
type: string
example: D4g3h5tBuVYK9
required: true
description: The ID of the address to delete
responses:
'200':
description: The address was successfully deleted
4XX:
$ref: '#/components/responses/response-4xx'
default:
$ref: '#/components/responses/response-default'
/account/payment-methods:
post:
summary: Add a payment method
operationId: accountAddPaymentMethod
x-speakeasy-name-override: AddPaymentMethod
description: 'Add a payment method to a shopper''s Bolt Account Wallet. For
security purposes, this request must come from your backend. <br/> **Note**:
Before using this API, the credit card details must be tokenized by Bolt''s
credit card tokenization service. Please review our [Bolt Payment Field Component](https://help.boltapp.com/products/ignite/api-implementation/#enhance-payments)
or [Install the Bolt Tokenizer](https://help.boltapp.com/developers/references/bolt-tokenizer)
documentation.'
tags:
- Account
security:
- oauth:
- bolt.account.manage
api-key: []
parameters:
- $ref: '#/components/parameters/x-publishable-key'
- $ref: '#/components/parameters/x-merchant-client-id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payment-method'
examples:
credit-card-address-reference-id:
$ref: '#/components/examples/credit-card-with-address-id'
credit-card-address-reference-explicit:
$ref: '#/components/examples/credit-card-with-address-explicit'
responses:
'200':
description: The payment method was successfully added
content:
application/json:
schema:
$ref: '#/components/schemas/payment-method'
4XX:
$ref: '#/components/responses/response-payment-method-error'
default:
$ref: '#/components/responses/response-default'
/account/payment-methods/{id}:
delete:
summary: Delete an existing payment method
operationId: accountPaymentMethodDelete
x-speakeasy-name-override: DeletePaymentMethod
description: Delete an existing payment method. Deleting a payment method does
not invalidate or remove it from transactions or orders that are associated
with it.
tags:
- Account
security:
- oauth:
- bolt.account.manage
api-key: []
parameters:
- $ref: '#/components/parameters/x-publishable-key'
- $ref: '#/components/parameters/x-merchant-client-id'
- in: path
name: id
schema:
type: string
example: D4g3h5tBuVYK9
required: true
description: The ID of the payment method to delete
responses:
'200':
description: The payment method was successfully deleted
4XX:
$ref: '#/components/responses/response-4xx'
default:
$ref: '#/components/responses/response-default'
/payments:
post:
summary: Initialize a Bolt payment for logged in shoppers
operationId: paymentsInitialize
x-speakeasy-group: Payments.LoggedIn
x-speakeasy-name-override: Initialize
description: 'Initialize a Bolt logged-in shopper''s intent to pay for a cart,
using the specified payment method. Payments must be finalized before indicating
the payment result to the shopper. Some payment methods will finalize automatically
after initialization. For these payments, they will transition directly to
"finalized" and the response from Initialize Payment will contain a finalized
payment.
'
tags:
- Payments
security:
- oauth:
- bolt.account.manage
api-key: []
parameters:
- $ref: '#/components/parameters/x-publishable-key'
- $ref: '#/components/parameters/x-merchant-client-id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payment-initialize-request'
examples:
reference:
$ref: '#/components/examples/payment-initialize-payment-method-reference'
credit_card:
$ref: '#/components/examples/payment-initialize-payment-method-credit-card'
paypal:
$ref: '#/components/examples/payment-initialize-payment-method-paypal'
responses:
'200':
description: The payment was successfully initialized, and was either immediately
finalized or is pending
content:
application/json:
schema:
$ref: '#/components/schemas/payment-response'
examples:
finalized:
$ref: '#/components/examples/payment-response-finalized'
pending:
$ref: '#/components/examples/payment-response-pending'
4XX:
$ref: '#/components/responses/response-payment-error'
default:
$ref: '#/components/responses/response-default'
/payments/{id}:
post:
summary: Finalize a pending payment
operationId: paymentsAction
x-speakeasy-group: Payments.LoggedIn
x-speakeasy-name-override: PerformAction
description: Finalize a pending payment being made by a Bolt logged-in shopper.
Upon receipt of a finalized payment result, payment success should be communicated
to the shopper.
tags:
- Payments
security:
- oauth:
- bolt.account.manage
api-key: []
parameters:
- $ref: '#/components/parameters/x-publishable-key'
- $ref: '#/components/parameters/x-merchant-client-id'
- in: path
name: id
schema:
type: string
example: iKv7t5bgt1gg
required: true
description: The ID of the payment to operate on
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payment-action-request'
responses:
'200':
description: The action was successfully applied to the pending payment
content:
application/json:
schema:
$ref: '#/components/schemas/payment-response'
examples:
finalized:
$ref: '#/components/examples/payment-response-finalized'
4XX:
$ref: '#/components/responses/response-4xx'
default:
$ref: '#/components/responses/response-default'
/guest/payments:
post:
summary: Initialize a Bolt payment for guest shoppers
operationId: guestPaymentsInitialize
x-speakeasy-group: Payments.Guest
x-speakeasy-name-override: Initialize
description: Initialize a Bolt guest shopper's intent to pay for a cart, using
the specified payment method. Payments must be finalized before indicating
the payment result to the shopper. Some payment methods will finalize automatically
after initialization. For these payments, they will transition directly to
"finalized" and the response from Initialize Payment will contain a finalized
payment.
tags:
- Payments
security:
- api-key: []
parameters:
- $ref: '#/components/parameters/x-publishable-key'
- $ref: '#/components/parameters/x-merchant-client-id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/guest-payment-initialize-request'
examples:
credit_card:
$ref: '#/components/examples/payment-initialize-guest-payment-method-credit-card'
paypal:
$ref: '#/components/examples/payment-initialize-guest-payment-method-paypal'
responses:
'200':
description: The payment was successfully initialized, and was either immediately
finalized or is pending
content:
application/json:
schema:
$ref: '#/components/schemas/payment-response'
examples:
finalized:
$ref: '#/components/examples/payment-response-finalized'
pending:
$ref: '#/components/examples/payment-response-pending'
4XX:
$ref: '#/components/responses/response-payment-error'
default:
$ref: '#/components/responses/response-default'
/guest/payments/{id}:
post:
summary: Finalize a pending guest payment
operationId: guestPaymentsAction
x-speakeasy-group: Payments.Guest
x-speakeasy-name-override: PerformAction
description: Finalize a pending payment being made by a Bolt guest shopper.
Upon receipt of a finalized payment result, payment success should be communicated
to the shopper.
tags:
- Payments
security:
- api-key: []
parameters:
- $ref: '#/components/parameters/x-publishable-key'
- $ref: '#/components/parameters/x-merchant-client-id'
- in: path
name: id
schema:
type: string
example: iKv7t5bgt1gg
required: true
description: The ID of the guest payment to operate on
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/payment-action-request'
responses:
'200':
description: The action was successfully applied to the pending guest payment
content:
application/json:
schema:
$ref: '#/components/schemas/payment-response'
4XX:
$ref: '#/components/responses/response-4xx'
default:
$ref: '#/components/responses/response-default'
/orders:
post:
summary: Create an order that was prepared outside the Bolt ecosystem.
operationId: ordersCreate
description: Create an order that was prepared outside the Bolt ecosystem. Some
Bolt-powered flows automatically manage order creation - in those flows the
order ID will be provided separately and not through this API.
tags:
- Orders
security:
- api-key: []
parameters:
- $ref: '#/components/parameters/x-publishable-key'
- $ref: '#/components/parameters/x-merchant-client-id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/order'
examples:
reference:
$ref: '#/components/examples/order'
responses:
'200':
description: The order was successfuly created
content:
application/json:
schema:
$ref: '#/components/schemas/order-response'
examples:
finalized:
$ref: '#/components/examples/order-response'
4XX:
$ref: '#/components/responses/response-4xx'
default:
$ref: '#/components/responses/response-default'
/oauth/token:
post:
summary: Get OAuth token
operationId: oauthGetToken
x-speakeasy-name-override: GetToken
description: Retrieve a new or refresh an existing OAuth token.
tags:
- OAuth
security: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
oneOf:
- $ref: '#/components/schemas/authorization-code-request'
- $ref: '#/components/schemas/refresh-token-request'
examples:
authorization-code:
$ref: '#/components/examples/authorization-code'
refresh-token:
$ref: '#/components/examples/refresh-token'
responses:
'200':
description: Access token is successfully fetched
content:
application/json:
schema:
$ref: '#/components/schemas/get-access-token-response'
4XX:
$ref: '#/components/responses/response-4xx'
default:
$ref: '#/components/responses/response-default'
/callbacks/accounts:
post:
x-speakeasy-ignore: true
summary: Callback to update or create a full shopper account
operationId: callbackAccountUpsert
description: Create or update a shopper account with profile information, payment
and addresses. This is also known as the "upsert account" API, a combination
of update and insert.
tags:
- Callbacks
security: []
parameters:
- $ref: '#/components/parameters/x-bolt-hmac-sha256'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create-full-account'
responses:
'200':
description: The account details were successfully created/updated
4XX:
description: An error has occurred, and further details are contained in
the response.
default:
description: An error has occurred, and further details are contained in
the response.
/testing/accounts:
post:
summary: Create a test account
operationId: testingAccountCreate
x-speakeasy-name-override: CreateAccount
description: Create a Bolt shopper account for testing purposes.
tags:
- Testing
security:
- api-key: []
parameters:
- $ref: '#/components/parameters/x-publishable-key'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/account-test-creation-data'
responses:
'200':
description: The account was successfully created
content:
application/json:
schema:
$ref: '#/components/schemas/account-test-creation-data'
4XX:
$ref: '#/components/responses/response-4xx'
default:
$ref: '#/components/responses/response-default'
/testing/accounts/phones:
get:
summary: Get a random phone number
operationId: testingAccountPhoneGet
description: Get a random, fictitious phone number that is not assigned to any
existing Bolt account.
tags:
- Testing
security:
- api-key: []
parameters:
- $ref: '#/components/parameters/x-publishable-key'
responses:
'200':
description: Successfully generated a random, fictitious, unassigned phone
number.
content:
application/json:
schema:
$ref: '#/components/schemas/account-test-phone-data'
4XX:
$ref: '#/components/responses/response-4xx'
default:
$ref: '#/components/responses/response-default'
/testing/credit-cards:
post:
summary: Retrieve a tokenized test credit card
operationId: testingCreditCardGet
x-speakeasy-name-override: GetCreditCard
description: Retrieve a test credit card that can be used to process payments
in your Bolt testing environment. The response includes the card's Bolt credit
card token.
tags:
- Testing
security:
- api-key: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- type
properties:
type:
type: string
description: The expected authorization result when using the generated
token for a payment.
enum:
- approve
- decline
example: approve
responses:
'200':
description: Successfully generated test credit card details
content:
application/json:
schema:
$ref: '#/components/schemas/test-credit-card'
4XX:
$ref: '#/components/responses/response-4xx'
default:
$ref: '#/components/responses/response-default'
components:
securitySchemes:
api-key:
type: apiKey
in: header
name: X-API-Key
oauth:
flows:
authorizationCode:
authorizationUrl: /v1/oauth/authorize
refreshUrl: /v1/oauth/token
tokenUrl: /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 Single Sign-On
(SSO) by granting a JSON Web Token (JWT) that stores account data.
type: oauth2
parameters:
x-publishable-key:
description: The publicly shareable identifier used to identify your Bolt merchant
division.
in: header
name: X-Publishable-Key
required: true
schema:
type: string
x-merchant-client-id:
description: A unique identifier for a shopper's device, generated by Bolt.
The value is retrieved with `Bolt.state.merchantClientId` in your frontend
context, per-shopper. This header is required for proper attribution of this
operation to your analytics reports. Omitting this header may result in incorrect
statistics.
in: header
name: X-Merchant-Client-Id
required: false
schema:
type: string
x-bolt-hmac-sha256:
description: A Bolt-signed hash-based message authentication code (HMAC) to
verify that the sender is Bolt.
in: header
name: X-Bolt-Hmac-Sha256
required: true
schema:
type: string
responses:
response-default:
description: An error has occurred, and no further details are provided (e.g.
5xx errors)
response-4xx:
description: An error has occurred, and further details are contained in the
response
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/error'
- $ref: '#/components/schemas/field-error'
response-address-error:
description: The address is invalid and cannot be added, or some other error
has occurred
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/error'
- $ref: '#/components/schemas/field-error'
examples:
missing-input:
summary: A required field is missing
value:
.tag: invalid_input_parameter
field: country_code
message: country_code must be populated
invalid-input:
summary: A field has a malformed value that does not conform to the
schema
value:
.tag: invalid_input_parameter
field: country_code
message: country_code format is invalid
invalid-postal-code:
summary: The postal code is invalid
value:
.tag: invalid_input_parameter
field: postal_code
message: postal code 94404 is invalid for country CA
invalid-region:
summary: The region is missing or is invalid
value:
.tag: invalid_input_parameter
field: region
message: region BC is invalid for country US
response-payment-method-error:
description: The payment method is invalid and cannot be added, or some other
error has occurred
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/error'
- $ref: '#/components/schemas/field-error'
- $ref: '#/components/schemas/credit-card-error'
examples:
missing-input:
summary: A required field is missing
value:
.tag: invalid_input_parameter
message: token is required
field: token
invalid-input:
summary: A field has a malformed value that does not conform to the
schema
value:
.tag: invalid_input_parameter
message: last4 value 104 is invalid
field: last4
invalid-credit-card:
summary: The credit card payment method could not be added because it
was declined
value:
.tag: declined_invalid_cvv
message: The payment was declined because the CVV is not valid
response-payment-error:
description: The payment operation cannot complete
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/error'
- $ref: '#/components/schemas/field-error'
- $ref: '#/components/schemas/three-ds-error'
- $ref: '#/components/schemas/cart-error'
- $ref: '#/components/schemas/credit-card-error'
examples:
missing-input:
summary: A required field is missing
value:
.tag: invalid_input_parameter
message: cart is required
field: cart
invalid-cart:
summary: The operation could not be completed because the cart fails
validation
value:
.tag: payment_already_exists
message: A payment for this order already exists
invalid-credit-card:
summary: The credit card payment method could not be added because it
was declined
value:
.tag: declined_invalid_cvv
message: The payment was declined because the CVV is not valid
three-ds-authentication-failed:
summary: 3DS Cardinal authentication failed
value:
.tag: three_ds_authentication_failed
message: 3DS Cardinal authentication failed
three-ds-verification-failed:
summary: 3DS verification check failed
value:
.tag: three_ds_verification_failed
message: 3DS verification failed
three-ds-reference-missing:
summary: 3DS reference is missing in the request
value:
.tag: three_ds_reference_missing
message: 3DS reference is missing in the request
schemas:
country-code:
type: string
description: The country (in its ISO 3166 alpha-2 format) associated with this
address.
enum:
- AF
- AX
- AL
- DZ
- AS
- AD
- AO
- AI
- AQ
- AG
- AR
- AM
- AW
- AU
- AT
- AZ
- BH
- BS
- BD
- BB
- BY
- BE
- BZ
- BJ
- BM
- BT
- BO
- BQ
- BA
- BW
- BV
- BR
- IO
- BN
- BG
- BF
- BI
- KH
- CM
- CA
- CV
- KY
- CF
- TD
- CL
- CN
- CX
- CC
- CO
- KM
- CG
- CD
- CK
- CR
- CI
- HR
- CU
- CW
- CY
- CZ
- DK
- DJ
- DM
- DO
- EC
- EG
- SV
- GQ
- ER
- EE
- ET
- FK
- FO
- FJ
- FI
- FR
- GF
- PF
- TF
- GA
- GM
- GE
- DE
- GH
- GI
- GR
- GL
- GD
- GP
- GU
- GT
- GG
- GN
- GW
- GY
- HT
- HM
- VA
- HN
- HK
- HU
- IS
- IN
- ID
- IR
- IQ
- IE
- IM
- IL
- IT
- JM
- JP
- JE
- JO
- KZ
- KE
- KI
- KP
- KR
- KW
- KG
- LA
- LV
- LB
- LS
- LR
- LY
- LI
- LT
- LU
- MO
- MK
- MG
- MW
- MY
- MV
- ML
- MT
- MH
- MQ
- MR
- MU
- YT
- MX
- FM
- MD
- MC
- MN
- ME
- MS
- MA
- MZ
- MM
- NA
- NR
- NP
- NL
- NC
- NZ
- NI
- NE
- NG
- NU
- NF
- MP
- 'NO'
- OM
- PK
- PW
- PS
- PA
- PG
- PY
- PE
- PH
- PN
- PL
- PT
- PR
- QA
- RE
- RO
- RU
- RW
- BL
- SH
- KN
- LC
- MF
- PM
- VC
- WS
- SM
- ST
- SA
- SN
- RS
- SC
- SL
- SG
- SX
- SK
- SI
- SB
- SO
- ZA
- GS
- SS
- ES
- LK
- SD
- SR
- SJ
- SZ
- SE
- CH
- SY
- TW
- TJ
- TZ
- TH
- TL
- TG
- TK
- TO
- TT
- TN
- TR
- TM
- TC
- TV
- UG
- UA
- AE
- GB
- US
- UM
- UY
- UZ
- VU
- VE
- VN
- VG
- VI
- WF
- EH
- YE
- ZM
- ZW
example: US
x-oapi-codegen-extra-tags:
validate: country,required
x-order: 11
address-listing:
type: object
description: An address saved on an account, i.e. a physical address plus any
additional account-specific metadata.
required:
- first_name
- last_name
- street_address1
- locality
- postal_code
- country_code
# --- truncated at 32 KB (104 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bolt-financial/refs/heads/main/openapi/bolt-financial-embeddable-checkout-v3-openapi.yml