Bolt Orders API

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