openapi: 3.2.0
info:
  version: 1.0.1
  title: Bolt API Reference Configuration API
  description: "Postman Collection:\n\n[![](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/9136127-55d2bde1-a248-473f-95b5-64cfd02fb445?action=collection%2Ffork&collection-url=entityId%3D9136127-55d2bde1-a248-473f-95b5-64cfd02fb445%26entityType%3Dcollection%26workspaceId%3D78beee89-4238-4c5f-bd1f-7e98978744b4#?env%5BBolt%20Sandbox%20Environment%5D=W3sia2V5IjoiYXBpX2Jhc2VfdXJsIiwidmFsdWUiOiJodHRwczovL2FwaS1zYW5kYm94LmJvbHQuY29tIiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InRrX2Jhc2UiLCJ2YWx1ZSI6Imh0dHBzOi8vc2FuZGJveC5ib2x0dGsuY29tIiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImFwaV9rZXkiLCJ2YWx1ZSI6IjxyZXBsYWNlIHdpdGggeW91ciBCb2x0IFNhbmRib3ggQVBJIGtleT4iLCJ0eXBlIjoic2VjcmV0IiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJwdWJsaXNoYWJsZV9rZXkiLCJ2YWx1ZSI6IjxyZXBsYWNlIHdpdGggeW91ciBCb2x0IFNhbmRib3ggcHVibGlzaGFibGUga2V5PiIsInR5cGUiOiJkZWZhdWx0IiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJkaXZpc2lvbl9pZCIsInZhbHVlIjoiPHJlcGxhY2Ugd2l0aCB5b3VyIEJvbHQgU2FuZGJveCBwdWJsaWMgZGl2aXNpb24gSUQ+IiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfV0=)\n\n## About\n A comprehensive Bolt API reference for interacting with Transactions, Orders, Product Catalog, Configuration, Testing, and much more.\n\n Note: You must also reference the [Merchant Callback API](/api-merchant) when building a managed checkout custom cart integration\n"
servers:
- url: https://api.boltapp.com
  description: The Production URL (Live Data).
- url: https://api-sandbox.boltapp.com
  description: The Sandbox URL (Test Data).
- url: https://api-staging.boltapp.com
  description: The Staging URL (Staged Data).
security:
- X-API-Key: []
- OAuth:
  - bolt.account.manage
  - bolt.account.view
tags:
- name: Configuration
  description: "Use this resource to retrieve and set Merchant Callback URLs. Bolt uses these URLs to exchange information with your commerce server. See our related guide [About the Merchant Callback API](https://help.boltapp.com/products/checkout/how-to-integrate/merchant-api-new/).   \n"
paths:
  /v1/merchant/callbacks:
    get:
      description: Retrieves callbacks URLs for a Bolt merchant division.
      operationId: getMerchantCallbacks
      parameters:
      - $ref: '#/components/parameters/division_id'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/merchant_callbacks_view'
          description: Merchant Callbacks Retrieved
        '400':
          $ref: '#/components/responses/merchant_callbacks_error_400'
        '403':
          $ref: '#/components/responses/merchant_callbacks_error_403'
      security:
      - X-API-Key: []
      summary: Get Callback URLs
      tags:
      - Configuration
    post:
      description: Configure callbacks URLs for a Bolt merchant division. This will store or override only the callback URLs that are specified in the request. Operations are fully transactional.
      operationId: setMerchantCallbacks
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/merchant_callbacks_input'
      responses:
        '200':
          description: Successfully sets callback URLs. No JSON schema is expected.
        '400':
          $ref: '#/components/responses/merchant_callbacks_error_400'
        '403':
          $ref: '#/components/responses/merchant_callbacks_error_403'
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_bolt_api_response'
          description: Request did not pass input validation. Check required fields are populated & meet input requirements.
      security:
      - X-API-Key: []
      summary: Set Callback URLs
      tags:
      - Configuration
  /v1/merchant/identifiers:
    get:
      description: This endpoint returns the merchant's public ID and the [publishable key](https://help.boltapp.com/developers/tools/api-keys/) related to the merchant division.
      operationId: getMerchantIdentifiers
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/merchant_identifiers_view'
          description: Merchant Identifiers Retrieved
        '403':
          $ref: '#/components/responses/merchant_identifier_error_403'
      security:
      - X-API-Key: []
      summary: Get Merchant Identifiers
      tags:
      - Configuration
components:
  schemas:
    merchant_identifiers_view:
      properties:
        merchant_divisions:
          $ref: '#/components/schemas/merchant_divisions_identifiers_view'
        merchant_id:
          description: The public ID of this merchant.
          example: 8fd9diIy59sj
          type: string
        signing_secret:
          description: Bolt generates one secret key per merchant and uses it to securely sign requests.
          example: xf833434fg2cffos92632aa6e1e4fc627a9385045gdj937fg2a127gi93cgos873
          type: string
      type: object
    merchant_callbacks_input:
      properties:
        callback_urls:
          description: List of callback URLs to configure
          example:
          - type: oauth_redirect
            url: https://example.com/1
          - type: oauth_logout
            url: https://example.com/2
          - type: get_account
            url: https://example.com/3
          items:
            properties:
              type:
                $ref: '#/components/schemas/merchant_callback_url_type'
              url:
                description: The full callback URL.
                type: string
            required:
            - url
            - type
            type: object
          type: array
        division_id:
          description: The unique ID associated to the merchant's Bolt Account division; Merchants can have different divisions to suit multiple use cases (storefronts, pay-by-link, phone order processing). Use the Bolt Merchant Dashboard to switch between divisions and find the division ID under `Merchant Division Public ID`.
          example: 3X9aPQ67-YrB
          type: string
      required:
      - division_id
      - callback_urls
      type: object
    error_bolt_api:
      properties:
        code:
          $ref: '#/components/schemas/code'
        message:
          $ref: '#/components/schemas/message'
      type: object
      description: Error object containing custom error information
    message:
      description: Human-readable description of the error for developers. Should not be shown to users and is not localized.
      example: The input is missing a required parameter.
      type: string
    request_result:
      description: Custom-defined Bolt result object.
      properties:
        success:
          $ref: '#/components/schemas/request_failed'
      type: object
    errors_bolt_api:
      items:
        $ref: '#/components/schemas/error_bolt_api'
      type: array
    merchant_divisions_identifiers_view:
      items:
        properties:
          division_id:
            description: The public ID of this division.
            example: IraJdeIgmdsO
            type: string
          publishable_key:
            description: The publishable key tied to this division.
            example: 8fd9diIy59sj.IraJdeIgmdsO.fd233434fg2c616cgo932aa6e1e4fc627a9385045gr395222a127gi93c595rg4
            type: string
        type: object
      type: array
    errors_bolt_api_response:
      properties:
        errors:
          $ref: '#/components/schemas/errors_bolt_api'
        result:
          $ref: '#/components/schemas/request_result'
      type: object
    code:
      description: Custom-defined Bolt error code. This can be used to programmatically react to specific errors.
      example: 2001005
      format: int64
      type: integer
    merchant_callbacks_view:
      properties:
        callback_urls:
          description: List of callback URLs retrieved
          example:
          - type: oauth_redirect
            url: https://example.com/1
          - type: oauth_logout
            url: https://example.com/2
          - type: get_account
            url: https://example.com/3
          items:
            properties:
              type:
                $ref: '#/components/schemas/merchant_callback_url_type'
              url:
                description: The full callback URL.
                type: string
            type: object
          type: array
      type: object
    merchant_callback_url_type:
      description: Bolt merchant division callback URL type
      enum:
      - oauth_redirect
      - oauth_logout
      - get_account
      - create_order
      - universal_merchant_api
      - shipping
      - tax
      - update_cart
      - debug
      - remote_api
      - product_info
      - support_page
      - account_page
      - mobile_app_domain
      - validate_additional_account_data
      - terms_of_service
      - privacy_policy
      - base_domain
      - confirmation_redirect
      type: string
    request_failed:
      example: false
      type: boolean
      description: Indicates that the request failed. This value is always false.
  responses:
    merchant_callbacks_error_403:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors_bolt_api_response'
      description: Invalid Merchant API Key
    merchant_identifier_error_403:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors_bolt_api_response'
      description: Invalid Merchant API Key
    merchant_callbacks_error_400:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errors_bolt_api_response'
      description: BAD REQUEST. Request is malformed or invalid value types are detected. division_id could be invalid.
  parameters:
    division_id:
      description: The unique ID associated to the merchant's Bolt Account division; Merchants can have different divisions to suit multiple use cases (storefronts, pay-by-link, phone order processing). You can view and switch between these divisions from the Bolt Merchant Dashboard.
      in: query
      name: division_id
      required: true
      schema:
        type: string
  securitySchemes:
    OAuth:
      description: 'Bolt utilizes the OAuth flow that developers can use to attain access to Bolt Account data via APIs.

        For all APIs that require authorization, please provide your `access_token` returned from `/v1/oauth/token` via the basic auth bearer header `Authorization: bearer ${TOKEN}`.

        [Read more about the OAuth token endpoint.](/api-bolt/#tag/OAuth)

        '
      flows:
        authorizationCode:
          authorizationUrl: https://api.boltapp.com/v1/oauth/authorize
          refreshUrl: https://api.boltapp.com/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 SSO by granting an id token JWT that stores account data. Not used in v1/account endpoints
          tokenUrl: https://api.boltapp.com/v1/oauth/token
      type: oauth2
    X-API-Key:
      description: Admins and Developers can obtain their Bolt API key from the Bolt Merchant Dashboard.
      in: header
      name: X-API-Key
      type: apiKey