Bolt Orders API
Use the Orders API to create and manage orders, including orders that have been placed outside the Bolt ecosystem.
OpenAPI Specification
openapi: 3.0.0
info:
version: 3.3.22
title: Bolt API Reference Account Orders 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: Orders
description: Use the Orders API to create and manage orders, including orders that have been placed outside the Bolt ecosystem.
paths:
/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'
components:
schemas:
cart-discount:
required:
- amount
type: object
properties:
amount:
$ref: '#/components/schemas/amount'
code:
type: string
description: Discount code.
maxLength: 1024
example: SUMMER10DISCOUNT
details_url:
type: string
description: Used to provide a link to additional details, such as a landing page, associated with the discount offering.
maxLength: 8192
format: url
example: https://www.example.com/SUMMER-SALE
processor-response:
description: Raw authorization response from the payment processor
properties:
content_type:
type: string
example: application/json
api_version:
type: string
example: '3.3'
text:
type: string
example: <?xml version="1.0" encoding="UTF-8"?> <transaction> <id>bfraj39q</id> <status>authorized</status> <type>sale</type> <currency-iso-code>USD</currency-iso-code> <amount>57.71</amount> <amount-requested>57.71</amount-requested> <merchant-account-id>GenericMerchant</merchant-account-id> <order-id>ORDER123456</order-id> <created-at type="datetime">2024-11-20T12:36:53Z</created-at> <updated-at type="datetime">2024-11-20T12:36:54Z</updated-at> <customer> <first-name>John</first-name> <last-name>Doe</last-name> <email>example@example.com</email> <phone>1234567890</phone> <international-phone></international-phone> </customer> <billing> <first-name>John</first-name> <last-name>Doe</last-name> <street-address>123 Generic St</street-address> <locality>GenericCity</locality> <region>GenericRegion</region> <postal-code>12345</postal-code> <country-name>GenericCountry</country-name> <country-code-alpha2>GC</country-code-alpha2> <country-code-alpha3>GCR</country-code-alpha3> <country-code-numeric>999</country-code-numeric> <international-phone></international-phone> </billing> <refund-ids type="array"></refund-ids> <partial-settlement-transaction-ids type="array"></partial-settlement-transaction-ids> <shipping> <international-phone></international-phone> </shipping> <custom-fields></custom-fields> <account-funding-transaction type="boolean">false</account-funding-transaction> <avs-postal-code-response-code>M</avs-postal-code-response-code> <avs-street-address-response-code>M</avs-street-address-response-code> <cvv-response-code>I</cvv-response-code> <processor-authorization-code>123456</processor-authorization-code> <processor-response-code>1000</processor-response-code> <processor-response-text>Approved</processor-response-text> <tax-exempt type="boolean">false</tax-exempt> <processed-with-network-token type="boolean">false</processed-with-network-token> <credit-card> <image-url>https://assets.braintreegateway.com/payment_method_logo/unknown.png?environment=production</image-url> <is-network-tokenized type="boolean">false</is-network-tokenized> <prepaid>Unknown</prepaid> <healthcare>Unknown</healthcare> <debit>Unknown</debit> <durbin-regulated>Unknown</durbin-regulated> <commercial>Unknown</commercial> <payroll>Unknown</payroll> <issuing-bank>Unknown</issuing-bank> <country-of-issuance>Unknown</country-of-issuance> <product-id>Unknown</product-id> <venmo-sdk type="boolean">false</venmo-sdk> </credit-card> <apple-pay> <prepaid>No</prepaid> <healthcare>Unknown</healthcare> <debit>No</debit> <durbin-regulated>Unknown</durbin-regulated> <commercial>No</commercial> <payroll>Unknown</payroll> <issuing-bank>GenericBank</issuing-bank> <country-of-issuance>GCR</country-of-issuance> <product-id>Unknown</product-id> <bin>411111</bin> <card-type>Apple Pay - GenericCard</card-type> <last-4>1234</last-4> <expiration-month>12</expiration-month> <expiration-year>2028</expiration-year> <image-url>https://assets.braintreegateway.com/payment_method_logo/apple_pay.png?environment=production</image-url> <payment-instrument-name>Card 1234</payment-instrument-name> <source-description>Card 1234</source-description> </apple-pay> <status-history type="array"> <status-event> <timestamp type="datetime">2024-11-20T12:36:54Z</timestamp> <status>authorized</status> <amount>57.71</amount> <transaction-source>api</transaction-source> </status-event> </status-history> <subscription></subscription> <add-ons type="array"></add-ons> <discounts type="array"></discounts> <descriptor></descriptor> <recurring type="boolean">false</recurring> <channel></channel> <disbursement-details></disbursement-details> <disputes type="array"></disputes> <authorization-adjustments type="array"></authorization-adjustments> <payment-instrument-type>generic_card</payment-instrument-type> <processor-settlement-response-code></processor-settlement-response-code> <processor-settlement-response-text></processor-settlement-response-text> <network-transaction-id>123456789012345</network-transaction-id> <processor-response-type>approved</processor-response-type> <authorization-expires-at type="datetime">2024-11-27T12:36:54Z</authorization-expires-at> <retry-ids type="array"></retry-ids> <retried type="boolean">false</retried> <refund-global-ids type="array"></refund-global-ids> <partial-settlement-transaction-global-ids type="array"></partial-settlement-transaction-global-ids> <global-id>generic_global_id</global-id> <retry-global-ids type="array"></retry-global-ids> <retrieval-reference-number>123456789012345</retrieval-reference-number> <installments type="array"></installments> <refunded-installments type="array"></refunded-installments> <merchant-address></merchant-address> <pin-verified type="boolean">false</pin-verified> <payment-receipt> <id>bfraj39q</id> <global-id>generic_global_id</global-id> <amount>57.71</amount> <currency-iso-code>USD</currency-iso-code> <processor-response-code>1000</processor-response-code> <processor-response-text>Approved</processor-response-text> <processor-authorization-code>123456</processor-authorization-code> <merchant-address></merchant-address> <type>sale</type> <pin-verified type="boolean">false</pin-verified> </payment-receipt> </transaction>
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
cart:
required:
- total
- tax
- order_reference
type: object
properties:
order_reference:
type: string
description: This value is used by Bolt as an external reference to a given order. This reference must be unique per successful transaction.
example: order_100
order_description:
type: string
description: Used optionally to pass additional information like order numbers or other IDs as needed.
maxLength: 1024
example: 'Order #1234567890'
display_id:
type: string
description: A shopper-facing identifier corresponding to the order reference associated with this transaction.
maxLength: 128
example: '215614191'
shipments:
type: array
items:
$ref: '#/components/schemas/cart-shipment'
discounts:
type: array
items:
$ref: '#/components/schemas/cart-discount'
items:
type: array
items:
$ref: '#/components/schemas/cart-item'
total:
description: The total amount of the cart including its items and taxes (if applicable).
$ref: '#/components/schemas/amount'
tax:
$ref: '#/components/schemas/amount'
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'
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
transaction:
type: object
properties:
reference:
type: string
example: OBYG-X1PX-FN55
authorizations:
description: Payment authorization events attached to a transaction
type: array
items:
$ref: '#/components/schemas/transaction-authorization'
amount:
type: object
description: A monetary amount, i.e. a base unit amount and a supported currency.
required:
- currency
- units
properties:
currency:
type: string
description: A supported currency.
enum:
- AUD
- CAD
- EUR
- GBP
- USD
example: USD
units:
type: integer
description: A monetary amount, represented in its base units (e.g. USD/EUR cents).
format: int64
example: 900
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
order:
type: object
required:
- profile
- cart
properties:
profile:
$ref: '#/components/schemas/profile'
cart:
$ref: '#/components/schemas/cart'
cart-shipment:
type: object
properties:
address:
$ref: '#/components/schemas/address-reference'
cost:
$ref: '#/components/schemas/amount'
carrier:
type: string
description: The name of the carrier selected.
example: FedEx
order-response:
type: object
required:
- id
- transaction
properties:
id:
type: string
format: id
example: iKv7t5bgt1gg
transaction:
$ref: '#/components/schemas/transaction'
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
transaction-authorization:
type: object
properties:
processor_reference:
type: string
example: 123456789XYZ
processor_response:
$ref: '#/components/schemas/processor-response'
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
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.
cart-item:
type: object
required:
- name
- reference
- total_amount
- unit_price
- quantity
properties:
name:
description: The name of a given item.
type: string
maxLength: 1024
example: Bolt Swag Bag
reference:
type: string
description: This value is used by Bolt as an external reference to a given item.
maxLength: 1024
example: item_100
description:
type: string
description: A human-readable description of this cart item.
example: Large tote with Bolt logo.
seller_id:
type: string
description: External reference ID for a marketplace seller.
example: seller_123
total_amount:
$ref: '#/components/schemas/amount'
unit_price:
type: integer
description: The item's unit price, i.e. the cost of a single item exclusive of tax and discounts.
format: int64
example: 1000
quantity:
type: integer
description: The number of units that comprise this cart item.
format: int64
maximum: 15000
example: 1
image_url:
type: string
description: Used to provide a link to the image associated with the item.
maxLength: 8192
example: https://www.example.com/products/123456/images/1.png
format: url
subscription_plan_id:
type: string
description: Subscription Plan ID that assigns this item to a specific subscription plan.
maxLength: 1024
example: spl_123
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
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)
examples:
order:
summary: An order created outside the Bolt ecosystem
value:
profile:
first_name: Charlie
last_name: Dunn
email: charlie@example.com
phone: '+14085551111'
cart:
total:
units: 1000
currency: USD
tax:
units: 100
currency: USD
order_reference: instore_20240116-878
order_description: 'Order #878'
display_id: 20240116-878
items:
- name: Red Fidget Spinner
reference: sku-984
description: Single-packed fidget spinner, red
total_amount:
units: 1000
currency: USD
unit_price: 1000
quantity: 1
image_url: https://www.example.com/products/984/image.png
shipments:
- cost:
units: 10000
currency: USD
carrier: FedEx
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
order-response:
summary: The order was successfully created
value:
id: 3Cxr2keCtxju
transaction:
reference: 2ZF2-WZ3J-WD2Y
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
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