Bolt Account API
Use the Accounts API to access shoppers' accounts to empower your checkout and facilitate shoppers' choices.
OpenAPI Specification
openapi: 3.0.0
info:
version: 3.3.22
title: Bolt API Reference Account 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: Account
description: Use the Accounts API to access shoppers' accounts to empower your checkout and facilitate shoppers' choices.
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.bolt.com/products/ignite/api-implementation/#enhance-payments) or [Install the Bolt Tokenizer](https://help.bolt.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'
components:
responses:
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-default:
description: An error has occurred, and no further details are provided (e.g. 5xx errors)
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-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
schemas:
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
credit-card-error:
type: object
required:
- .tag
- message
properties:
.tag:
type: string
enum:
- declined
- declined_invalid_amount
- declined_invalid_cvv
- declined_invalid_merchant
- declined_invalid_number
- declined_expired
- declined_call_issuer
- declined_unsupported
description: The type of error returned
example: declined_invalid_cvv
message:
type: string
description: A human-readable error message, which might include information specific to the request that was made.
example: The payment was declined because the CVV is not valid
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-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-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-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
error:
type: object
required:
- .tag
- message
properties:
.tag:
type: string
enum:
- unauthorized
- forbidden
- unprocessable_request
- not_found
description: The type of error returned
example: unprocessable_request
message:
type: string
description: A human-readable error message, which might include information specific to the request that was made.
example: We were unable to process your request.
field-error:
type: object
description: An error that pertains to validation of a specific field in the request.
required:
- .tag
- message
- field
properties:
.tag:
type: string
enum:
- invalid_input_parameter
description: The type of error returned
example: invalid_input_parameter
message:
type: string
description: A human-readable error message, which might include information specific to the request that was made.
example: We were unable to process your request.
field:
type: string
description: The field (in its hierarchical form) that is failing validation.
example: address.phone
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
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bolt/refs/heads/main/openapi/bolt-account-api-openapi.yml