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.
**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: 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-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-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 examples: address-all-fields: summary: A sample address where all fields, including optional fields, are set value: first_name: Alice last_name: Baker company: ACME Corporation street_address1: 535 Mission St, Ste 1401 street_address2: c/o Shipping Department locality: San Francisco postal_code: '94105' region: CA country_code: US email: alice@example.com phone: '+14155550199' is_default: true address-some-fields: summary: A sample address where only required fields are set value: first_name: Jean last_name: Blanc street_address1: 77 Rue Frédéric Chopin locality: Versailles postal_code: '78000' country_code: FR credit-card-with-address-id: summary: Add a credit card, providing a billing address ID corresponding to an existing address on the shopper's account value: .tag: credit_card type: credit network: visa bin: '411111' last4: '1004' expiration: 2025-03 token: a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0 billing_address: .tag: id id: D4g3h5tBuVYK9 credit-card-with-address-explicit: summary: Add a credit card, providing an explicit billing address value: .tag: credit_card type: credit network: visa bin: '411111' last4: '1004' expiration: 2025-03 token: a1B2c3D4e5F6G7H8i9J0k1L2m3N4o5P6Q7r8S9t0 billing_address: .tag: explicit first_name: Charlie last_name: Dunn street_address1: 535 Mission St locality: San Francisco postal_code: '94105' region: CA country_code: US 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