Bolt Callbacks API
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.
OpenAPI Specification
openapi: 3.0.0
info:
version: 3.3.22
title: Bolt API Reference Account Callbacks API
description: A comprehensive Bolt API reference for interacting with Accounts, Payments, Orders and more.
termsOfService: https://www.bolt.com/end-user-terms
contact:
name: Bolt
email: merchantsupport@bolt.com
url: https://help.bolt.com/api-bolt/
servers:
- url: https://{environment}.bolt.com/v3
variables:
environment:
enum:
- api
- api-sandbox
default: api-sandbox
tags:
- 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.
paths:
/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.
components:
schemas:
create-full-account:
type: object
properties:
account_details:
$ref: '#/components/schemas/account'
customer_data_id:
type: string
description: A unique identifier for this account on your cart platform.
example: 5FEB9028D
address-reference-partial:
type: object
title: Partial Address Reference
required:
- .tag
- postal_code
properties:
.tag:
type: string
enum:
- partial
description: The type of address reference
example: partial
x-order: 0
postal_code:
type: string
description: The postal code associated with the credit card billing address.
example: '94105'
x-order: 1
payment-method-klarna-paynow:
type: object
required:
- .tag
- return_url
title: Klarna Pay Now Payment Method
properties:
.tag:
type: string
enum:
- klarna_paynow
example: klarna_paynow
return_url:
type: string
description: Return URL to return to after payment completion in Klarna.
format: url
writeOnly: true
example: https://www.example.com/handle_klarna_paynow_success
payment-method-googlepay:
title: Googlepay Payment Method
allOf:
- type: object
required:
- .tag
- type
properties:
.tag:
type: string
enum:
- googlepay
example: googlepay
x-order: 0
id:
type: string
format: id
readOnly: true
example: X5h6j8uLpVGK
x-order: 1
type:
type: string
description: The type of payment method
example: googlepay
x-order: 2
billing_address:
$ref: '#/components/schemas/address-reference'
- $ref: '#/components/schemas/credit-card'
payment-method-affirm:
type: object
required:
- .tag
- return_url
title: Affirm Payment Method
properties:
.tag:
type: string
enum:
- affirm
example: affirm
return_url:
type: string
description: Return URL to return to after payment completion in Affirm.
format: url
writeOnly: true
example: https://www.example.com/handle_affirm_success
address-reference:
oneOf:
- $ref: '#/components/schemas/address-reference-id'
- $ref: '#/components/schemas/address-reference-explicit'
- $ref: '#/components/schemas/address-reference-partial'
discriminator:
propertyName: .tag
mapping:
id: '#/components/schemas/address-reference-id'
explicit: '#/components/schemas/address-reference-explicit'
partial: '#/components/schemas/address-reference-partial'
payment-method-afterpay:
type: object
required:
- .tag
- return_url
title: Afterpay Payment Method
properties:
.tag:
type: string
enum:
- afterpay
example: afterpay
return_url:
type: string
description: Return URL to return to after payment completion in Afterpay.
format: url
writeOnly: true
example: https://www.example.com/handle_afterpay_success
credit-card:
required:
- network
- bin
- last4
- expiration
- token
type: object
properties:
network:
$ref: '#/components/schemas/credit-card-network'
bin:
type: string
description: The Bank Identification Number (BIN). This is the first 4 to 8 digits of the account number.
pattern: ^\d+$
example: '411111'
last4:
type: string
description: The account number's last four digits.
pattern: ^\d{4}$
example: '1004'
expiration:
type: string
description: The expiration date, in YYYY-MM format.
pattern: ^\d{4}-\d{2}$
example: 2029-03
token:
type: string
description: The Bolt token associated with the credit card.
writeOnly: true
example: a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0
affirm_vcn_token:
type: string
description: The checkout token associated with Affirm VCN credit cards.
example: a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0
default:
type: boolean
description: Indicates whether this credit card is the default payment method.
example: true
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
payment-method-klarna:
type: object
required:
- .tag
- return_url
title: Klarna Payment Method
properties:
.tag:
type: string
enum:
- klarna
example: klarna
return_url:
type: string
description: Return URL to return to after payment completion in Klarna.
format: url
writeOnly: true
example: https://www.example.com/handle_klarna_success
profile:
type: object
description: An account's identifying information.
required:
- first_name
- last_name
- email
properties:
first_name:
type: string
description: The given name of the person associated with this profile.
example: Alice
x-order: 1
last_name:
type: string
description: The last name of the person associated with this profile.
example: Baker
x-order: 2
email:
type: string
format: email
description: The email address asscoiated with this profile.
example: alice@example.com
x-order: 3
phone:
type: string
format: phone
description: The phone number associated with this profile.
example: '+14155550199'
x-order: 4
account:
type: object
required:
- addresses
- payment_methods
properties:
addresses:
type: array
description: A list of addresses associated with this account. These can be considered the "shipping addresses". The account's visible addresses are filtered according to the configured shipping destinations in your Bolt merchant dashboard. If no account addresses are available, use the billing address of the selected payment method.
items:
$ref: '#/components/schemas/address-listing'
payment_methods:
type: array
description: A list of payment methods associated with this account. The account's visible payment methods are filtered to include only cards that are chargeable.
items:
$ref: '#/components/schemas/payment-method'
profile:
$ref: '#/components/schemas/profile'
payment-method-klarna-account:
type: object
required:
- .tag
- return_url
title: Klarna Account Payment Method
properties:
.tag:
type: string
enum:
- klarna_account
example: klarna_account
return_url:
type: string
description: Return URL to return to after payment completion in Klarna.
format: url
writeOnly: true
example: https://www.example.com/handle_klarna_account_success
payment-method-applepay:
title: ApplePay Payment Method
allOf:
- type: object
required:
- .tag
- type
properties:
.tag:
type: string
enum:
- applepay
example: applepay
x-order: 0
id:
type: string
format: id
readOnly: true
example: X5h6j8uLpVGK
x-order: 1
type:
type: string
description: The type of payment method
example: applepay
x-order: 2
billing_address:
$ref: '#/components/schemas/address-reference'
- $ref: '#/components/schemas/credit-card'
- type: object
properties:
bolt_reference:
type: string
description: Bolt generated Applepay token id needed for token life cycle management.
example: a6f57b8c-3b12-4baf-9e77-0b9b2e3cb3d7
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
properties:
id:
type: string
format: id
description: The address's unique identifier.
readOnly: true
example: D4g3h5tBuVYK9
x-order: 1
first_name:
type: string
description: The first name of the person associated with this address.
example: Alice
x-order: 2
last_name:
type: string
description: The last name of the person associated with this address.
example: Baker
x-order: 3
company:
type: string
description: The company associated with this address.
example: ACME Corporation
x-order: 4
street_address1:
type: string
description: The street address associated with this address.
example: 535 Mission St, Ste 1401
x-order: 5
street_address2:
type: string
description: Any additional, optional, street address information associated with this address.
example: c/o Shipping Department
x-order: 6
locality:
type: string
description: The locality (e.g. city, town, etc...) associated with this address.
example: San Francisco
x-order: 7
postal_code:
type: string
description: The postal code associated with this address.
example: '94105'
x-order: 8
region:
type: string
description: The region or administrative area (e.g. state, province, county, etc...) associated with this address.
example: CA
x-order: 9
country_code:
$ref: '#/components/schemas/country-code'
email:
type: string
format: email
description: The email address associated with this address.
example: alice@example.com
x-order: 11
phone:
type: string
format: phone
description: The phone number associated with this address.
example: '+14155550199'
x-oapi-codegen-extra-tags:
validate: phone=strict
x-order: 12
is_default:
type: boolean
description: Whether or not this is the default address saved.
readOnly: true
example: true
address-reference-explicit:
type: object
title: Explicit Address Reference
required:
- .tag
- first_name
- last_name
- street_address1
- locality
- postal_code
- country_code
properties:
.tag:
type: string
enum:
- explicit
description: The type of address reference
example: explicit
x-order: 0
id:
type: string
format: id
description: The address's unique identifier.
readOnly: true
example: D4g3h5tBuVYK9
x-order: 1
first_name:
type: string
description: The first name of the person associated with this address.
example: Alice
x-order: 2
last_name:
type: string
description: The last name of the person associated with this address.
example: Baker
x-order: 3
company:
type: string
description: The company associated with this address.
example: ACME Corporation
x-order: 4
street_address1:
type: string
description: The street address associated with this address.
example: 535 Mission St, Ste 1401
x-order: 5
street_address2:
type: string
description: Any additional, optional, street address information associated with this address.
example: c/o Shipping Department
x-order: 6
locality:
type: string
description: The locality (e.g. city, town, etc...) associated with this address.
example: San Francisco
x-order: 7
postal_code:
type: string
description: The postal code associated with this address.
example: '94105'
x-order: 8
region:
type: string
description: The region or administrative area (e.g. state, province, county, etc...) associated with this address.
example: CA
x-order: 9
country_code:
$ref: '#/components/schemas/country-code'
email:
type: string
format: email
description: The email address associated with this address.
example: alice@example.com
x-order: 11
phone:
type: string
format: phone
description: The phone number associated with this address.
example: '+14155550199'
x-order: 12
address-reference-id:
type: object
title: Address ID Reference
required:
- .tag
- id
properties:
.tag:
type: string
enum:
- id
description: The type of address reference
example: id
id:
type: string
format: id
description: The address's ID
example: D4g3h5tBuVYK9
credit-card-network:
type: string
description: The credit card's network.
enum:
- visa
- mastercard
- amex
- discover
- jcb
- dinersclub
- unionpay
- alliancedata
- citiplcc
example: visa
x-oapi-codegen-extra-tags:
validate: required
payment-method-paypal:
type: object
title: PayPal Payment Method
required:
- .tag
- success_url
- cancel_url
properties:
.tag:
type: string
enum:
- paypal
example: paypal
x-order: 0
success_url:
type: string
description: Redirect URL for successful PayPal transaction.
format: url
writeOnly: true
example: https://www.example.com/paypal-callback/success
cancel_url:
type: string
description: Redirect URL for canceled PayPal transaction.
format: url
writeOnly: true
example: https://www.example.com/paypal-callback/cancel
payment-method:
oneOf:
- $ref: '#/components/schemas/payment-method-credit-card'
- $ref: '#/components/schemas/payment-method-googlepay'
- $ref: '#/components/schemas/payment-method-applepay'
- $ref: '#/components/schemas/payment-method-paypal'
- $ref: '#/components/schemas/payment-method-affirm'
- $ref: '#/components/schemas/payment-method-afterpay'
- $ref: '#/components/schemas/payment-method-klarna'
- $ref: '#/components/schemas/payment-method-klarna-account'
- $ref: '#/components/schemas/payment-method-klarna-paynow'
discriminator:
propertyName: .tag
mapping:
credit_card: '#/components/schemas/payment-method-credit-card'
googlepay: '#/components/schemas/payment-method-googlepay'
applepay: '#/components/schemas/payment-method-applepay'
paypal: '#/components/schemas/payment-method-paypal'
affirm: '#/components/schemas/payment-method-affirm'
afterpay: '#/components/schemas/payment-method-afterpay'
klarna: '#/components/schemas/payment-method-klarna'
klarna_account: '#/components/schemas/payment-method-klarna-account'
klarna_paynow: '#/components/schemas/payment-method-klarna-paynow'
payment-method-credit-card:
title: Credit Card Payment Method
allOf:
- type: object
required:
- .tag
- type
- billing_address
properties:
.tag:
type: string
enum:
- credit_card
example: credit_card
x-order: 0
id:
type: string
format: id
readOnly: true
example: X5h6j8uLpVGK
x-order: 1
type:
type: string
description: The type of payment method
example: credit_card
x-order: 2
billing_address:
$ref: '#/components/schemas/address-reference'
- $ref: '#/components/schemas/credit-card'
parameters:
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
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