BigCommerce Shipping Provider API

openapi: 3.0.0
info:
  title: BigCommerce Abandoned Cart Emails Shipping Provider API
  version: 3.0.0
  termsOfService: https://www.bigcommerce.com/terms
  description: Abandoned Cart Emails V3 API managing Handlebars-based emails.
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
  variables:
    store_hash:
      default: store_hash
      description: Permanent ID of the BigCommerce store.
  description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Shipping Provider
paths:
  /rate:
    post:
      description: "Request shipping rates. BigCommerce sends a request for shipping quotes to the shipping provider URL. The shipping provider responds with shipping quotes.\n\n> #### Note\n> * Substitute the host and path specific to the shipping provider for `your_app.example.com` and `rate`. \n> * The Send a Test Request feature is not currently supported for this endpoint.  "
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RateRequestPayload'
        description: Rate request object.
        required: true
      responses:
        '200':
          description: Quote response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateResponsePayload'
              examples:
                With shipping rates:
                  value:
                    quote_id: Lor
                    messages:
                    - text: ni
                      type: INFO
                    carrier_quotes:
                    - quotes:
                      - code: GND
                        display_name: cillum
                        cost:
                          currency: BEH
                          amount: 53116961.83460022
                        messages:
                        - text: deserunt
                          type: INFO
                        - text: ut
                          type: ERROR
                        - text: c
                          type: WARNING
                        - text: veniam
                          type: ERROR
                        description: el
                        rate_id: n
                        discounted_cost:
                          currency: VQD
                          amount: 16810732.187082157
                        dispatch_date: '1947-07-10'
                        transit_time:
                          units: DAYS
                          duration: 74
                      - code: GND
                        display_name: ''
                        cost:
                          currency: PRZ
                          amount: 85659359.530116
                        messages:
                        - text: consequat
                          type: ERROR
                        - text: eu e
                          type: WARNING
                        - text: adip
                          type: ERROR
                        - text: enim no
                          type: ERROR
                        - text: eu
                          type: ERROR
                        description: cillum ve
                        rate_id: ea ad
                        discounted_cost:
                          currency: XRQ
                          amount: 69218406.22440869
                        dispatch_date: '1954-03-05'
                        transit_time:
                          units: HOURS
                          duration: 21
                      - code: GND
                        display_name: dolor rep
                        cost:
                          currency: VOF
                          amount: 29865288.150019586
                        messages:
                        - text: in id
                          type: INFO
                        - text: et occa
                          type: ERROR
                        - text: esse dolo
                          type: INFO
                        - text: dolor
                          type: ERROR
                        - text: ex
                          type: ERROR
                        description: ullamco
                        rate_id: ''
                        discounted_cost:
                          currency: CKD
                          amount: 18401337.766514115
                        dispatch_date: '1993-06-23'
                        transit_time:
                          units: HOURS
                          duration: 54
                      carrier_info:
                        code: ''
                        display_name: c
                    - quotes:
                      - code: GND
                        display_name: labore
                        cost:
                          currency: OHQ
                          amount: 63679444.026082255
                        messages:
                        - text: offici
                          type: INFO
                        - text: dolore
                          type: ERROR
                        - text: nis
                          type: WARNING
                        - text: ma
                          type: WARNING
                        description: in r
                        rate_id: l
                        discounted_cost:
                          currency: UBE
                          amount: 40327578.11995282
                        dispatch_date: '1943-09-25'
                        transit_time:
                          units: DAYS
                          duration: 10
                      - code: GND
                        display_name: irure
                        cost:
                          currency: PEJ
                          amount: 56049316.6584908
                        messages:
                        - text: cillum a
                          type: INFO
                        description: nisi
                        rate_id: ''
                        discounted_cost:
                          currency: VFS
                          amount: 86177946.62739782
                        dispatch_date: '1999-01-13'
                        transit_time:
                          units: DAYS
                          duration: 11
                      carrier_info:
                        code: consect
                        display_name: eiusmod
                    - quotes:
                      - code: GND
                        display_name: ullamc
                        cost:
                          currency: NRB
                          amount: 75971681.09105605
                        messages:
                        - text: laborum
                          type: INFO
                        - text: proident i
                          type: WARNING
                        - text: sin
                          type: ERROR
                        - text: volup
                          type: ERROR
                        - text: deser
                          type: WARNING
                        description: am
                        rate_id: mo
                        discounted_cost:
                          currency: NPA
                          amount: 72743924.13626081
                        dispatch_date: '2006-01-17'
                        transit_time:
                          units: BUSINESS_DAYS
                          duration: 52
                      - code: GND
                        display_name: dolor
                        cost:
                          currency: RDZ
                          amount: 46371179.641438134
                        messages:
                        - text: ex
                          type: WARNING
                        - text: ipsum
                          type: WARNING
                        description: ''
                        rate_id: aute c
                        discounted_cost:
                          currency: SJL
                          amount: 60745150.4084129
                        dispatch_date: '1976-06-19'
                        transit_time:
                          units: DAYS
                          duration: 69
                      - code: GND
                        display_name: minim a
                        cost:
                          currency: SUR
                          amount: 97146769.48560241
                        messages:
                        - text: Lorem
                          type: INFO
                        description: de
                        rate_id: fu
                        discounted_cost:
                          currency: PCP
                          amount: 99728805.8108871
                        dispatch_date: '1962-05-18'
                        transit_time:
                          units: DAYS
                          duration: 10
                      - code: GND
                        display_name: ea occaeca
                        cost:
                          currency: YOG
                          amount: 51938381.743391246
                        messages:
                        - text: in irure
                          type: INFO
                        - text: c
                          type: INFO
                        - text: deserun
                          type: ERROR
                        - text: dolo
                          type: ERROR
                        description: dol
                        rate_id: U
                        discounted_cost:
                          currency: HMF
                          amount: 98693839.53819382
                        dispatch_date: '2010-08-15'
                        transit_time:
                          units: HOURS
                          duration: 31
                      - code: GND
                        display_name: sint
                        cost:
                          currency: TTO
                          amount: 65094224.57995142
                        messages:
                        - text: ut
                          type: INFO
                        description: labo
                        rate_id: anim ma
                        discounted_cost:
                          currency: ZMA
                          amount: 57479313.52475042
                        dispatch_date: '2008-10-24'
                        transit_time:
                          units: DAYS
                          duration: 55
                      carrier_info:
                        code: dol
                        display_name: commodo
                    - quotes:
                      - code: GND
                        display_name: sed
                        cost:
                          currency: BOE
                          amount: 9130506.016241236
                        messages:
                        - text: i
                          type: ERROR
                        - text: dolore
                          type: WARNING
                        - text: ut
                          type: INFO
                        - text: nos
                          type: ERROR
                        description: ''
                        rate_id: c
                        discounted_cost:
                          currency: QGD
                          amount: 81757709.40827666
                        dispatch_date: '1999-11-11'
                        transit_time:
                          units: HOURS
                          duration: 6
                      - code: GND
                        display_name: do aute
                        cost:
                          currency: IQW
                          amount: 83709032.8238562
                        messages:
                        - text: ess
                          type: ERROR
                        - text: an
                          type: WARNING
                        - text: Duis
                          type: ERROR
                        - text: ipsum
                          type: WARNING
                        - text: do
                          type: WARNING
                        description: amet
                        rate_id: veniam
                        discounted_cost:
                          currency: YYL
                          amount: 11005656.662449125
                        dispatch_date: '1980-05-16'
                        transit_time:
                          units: HOURS
                          duration: 32
                      carrier_info:
                        code: vel
                        display_name: laborum e
                Without shipping rates:
                  value:
                    quote_id: example_quote
                    messages: []
                    carrier_quotes: []
      summary: BigCommerce Request shipping rates
      tags:
      - Shipping Provider
      operationId: requestShippingRates
  /check_connection_options:
    post:
      description: "Validate connection options. BigCommerce sends a request to the shipping provider URL to check a merchantʼs connection credentials. The shipping provider sends a response indicating whether a merchant has valid credentials. \n\n> #### Note\n> * Substitute the host and path specific to the shipping provider for `your_app.example.com` and `check_connection_options`.  \n> * The Send a Test Request feature is not currently supported for this endpoint."
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckConnectionOptionsRequestPayload'
        description: Check connection options request.
        required: true
      responses:
        '200':
          description: Check connection options response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckConnectionOptionsResponsePayload'
              examples:
                response:
                  value:
                    valid: true
                    messages:
                    - text: adipi
                      type: WARNING
                    - text: nu
                      type: WARNING
                    - text: an
                      type: INFO
      summary: BigCommerce Validate connection options
      tags:
      - Shipping Provider
      operationId: validateConnectionOptions
components:
  schemas:
    RateRequestPayload:
      type: object
      title: Rate Request Payload
      description: Payload sent to a Shipping Provider to get quotes.
      properties:
        base_options:
          $ref: '#/components/schemas/BaseOptions'
        zone_options:
          $ref: '#/components/schemas/ZoneOptionsInstance'
        connection_options:
          $ref: '#/components/schemas/ConnectionOptionsInstance'
      required:
      - base_options
      x-internal: false
    CheckConnectionOptionsRequestPayload:
      type: object
      properties:
        connection_options:
          $ref: '#/components/schemas/ConnectionOptionsInstance'
      required:
      - connection_options
      title: Check Connection Options Request Payload
      description: 'The payload sent to a Shipping Provider to check that the store is connected to this provider.


        Each Shipping Provider will have different configurations for the payload.'
      x-internal: false
    RateResponsePayload:
      type: object
      properties:
        quote_id:
          type: string
          maxLength: 50
        messages:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
                minLength: 1
                maxLength: 500
              type:
                type: string
                enum:
                - INFO
                - WARNING
                - ERROR
            required:
            - text
            - type
            title: Message
            description: A simple string/type response for returning information.
        carrier_quotes:
          type: array
          items:
            type: object
            description: A grouping of carrier rates and optionally, info about that carrier.
            properties:
              carrier_info:
                type: object
                properties:
                  code:
                    type: string
                    maxLength: 50
                  display_name:
                    type: string
                    minLength: 1
                    maxLength: 100
                required:
                - code
                - display_name
              quotes:
                type: array
                items:
                  type: object
                  properties:
                    code:
                      description: A code describing the service.
                      type: string
                      minLength: 1
                      maxLength: 50
                      example: GND
                    display_name:
                      description: A display name for the service.
                      type: string
                      maxLength: 100
                    cost:
                      description: Value object for a money amount.
                      type: object
                      properties:
                        currency:
                          type: string
                          pattern: ^[A-Z]{3,3}$
                        amount:
                          type: number
                          minimum: 0
                      required:
                      - currency
                      - amount
                      title: Money Value
                    messages:
                      type: array
                      items:
                        type: object
                        properties:
                          text:
                            type: string
                            minLength: 1
                            maxLength: 500
                          type:
                            type: string
                            enum:
                            - INFO
                            - WARNING
                            - ERROR
                        required:
                        - text
                        - type
                        title: Message
                        description: A simple string/type response for returning information.
                    description:
                      type: string
                      maxLength: 500
                    rate_id:
                      type: string
                      maxLength: 50
                    discounted_cost:
                      description: Value object for a money amount. Optional field; merchants may request features.
                      type: object
                      properties:
                        currency:
                          type: string
                          pattern: ^[A-Z]{3,3}$
                        amount:
                          type: number
                          minimum: 0
                      required:
                      - currency
                      - amount
                      title: Money Value
                    dispatch_date:
                      type: string
                      format: date
                      description: Date at which carrier dispatches to the shipping destination. Optional field; merchants may request features.
                    transit_time:
                      type: object
                      properties:
                        units:
                          type: string
                          enum:
                          - BUSINESS_DAYS
                          - DAYS
                          - HOURS
                        duration:
                          type: integer
                          minimum: 1
                          maximum: 90
                      title: Transit Time Object
                      description: Value object for the length of time in transit.
                  required:
                  - code
                  - display_name
                  - cost
                  title: Rate Quote Object
                  description: A quote being returned as part of the rate request.
            required:
            - quotes
            title: Carrier Quote Object
      required:
      - quote_id
      - messages
      - carrier_quotes
      title: Rate Response Payload
      description: The response from the Shipping Service. Contains zero or more quotes.
      x-internal: false
    BaseOptions:
      description: The minimum required payload that is sent to retrieve rates.
      type: object
      title: Base Rate Request
      x-internal: false
      properties:
        origin:
          type: object
          title: Shipping Address
          description: Object representing a destination or origin address for items.
          required:
          - zip
          - country_iso2
          properties:
            street_1:
              type: string
              maxLength: 255
            street_2:
              type: string
              maxLength: 255
            zip:
              type: string
              maxLength: 20
              example: '94105'
            city:
              type: string
              maxLength: 50
              example: San Francisco
            state_iso2:
              type: string
              description: State in ISO_3166 2 format.
              maxLength: 2
            country_iso2:
              type: string
              description: Country in ISO_3166 2 format.
              maxLength: 2
              example: US
            address_type:
              description: Optional. Defaults to `RESIDENTIAL`.
              type: string
              enum:
              - RESIDENTIAL
              - COMMERCIAL
        destination:
          type: object
          title: Shipping Address
          description: Object representing a destination or origin address for items.
          required:
          - zip
          - country_iso2
          properties:
            street_1:
              type: string
              maxLength: 255
            street_2:
              type: string
              maxLength: 255
            zip:
              type: string
              maxLength: 20
              example: '94105'
            city:
              type: string
              maxLength: 50
              example: San Francisco
            state_iso2:
              type: string
              description: State in ISO_3166 2 format
              maxLength: 2
            country_iso2:
              type: string
              description: Country in ISO_3166 2 format
              maxLength: 2
              example: US
            address_type:
              description: Defaults to residential. Optional.
              type: string
              enum:
              - RESIDENTIAL
              - COMMERCIAL
            form_fields:
              type: object
              example:
                '1': selected_value
                '3': checkbox_selection_1
              description: Describes one or more [custom form fields](/docs/rest-storefront/forms). Property key is the global ID of a shipping address form field. When no custom fields exist, the object is empty.
              properties:
                <form field global ID>:
                  $ref: '#/components/schemas/FormFieldValue'
        items:
          type: array
          items:
            type: object
            description: A cart item along with its shipping-specific attributes.
            title: Rate Request Item
            properties:
              sku:
                type: string
                description: The variant SKU.
              variant_id:
                type: string
              product_id:
                type: string
              name:
                type: string
              length:
                description: Value object for a length measurement.
                type: object
                title: Dimension Value
                properties:
                  units:
                    type: string
                    enum:
                    - cm
                    - in
                  value:
                    type: number
                    minimum: 0
                required:
                - units
                - value
              width:
                description: Value object for a length measurement.
                type: object
                title: Dimension Value
                properties:
                  units:
                    type: string
                    enum:
                    - cm
                    - in
                  value:
                    type: number
                    minimum: 0
                required:
                - units
                - value
              height:
                description: Value object for a length measurement.
                type: object
                title: Dimension Value
                properties:
                  units:
                    type: string
                    enum:
                    - cm
                    - in
                  value:
                    type: number
                    minimum: 0
                required:
                - units
                - value
              weight:
                description: Value object for a weight measurement.
                type: object
                title: Weight Value
                properties:
                  units:
                    type: string
                    enum:
                    - oz
                    - g
                  value:
                    type: number
                    minimum: 0
                required:
                - units
                - value
              discounted_price:
                description: Value object for a money amount.
                type: object
                title: Money Value
                properties:
                  currency:
                    type: string
                    pattern: ^[A-Z]{3,3}$
                  amount:
                    type: number
                    minimum: 0
                required:
                - currency
                - amount
              declared_value:
                description: Value object for a money amount.
                type: object
                title: Money Value
                properties:
                  currency:
                    type: string
                    pattern: ^[A-Z]{3,3}$
                  amount:
                    type: number
                    minimum: 0
                required:
                - currency
                - amount
              quantity:
                type: number
                format: int32
              attributes:
                description: A list of arbitrary properties stored as part of the product or product variant meta fields. These consist of public fields specific to the carrier integration.
                type: array
                items:
                  type: object
                  title: Attribute Value
                  properties:
                    key:
                      type: string
                      description: The key associated with the meta field.
                    value:
                      type: string
                      description: The value associated with the meta field.
                    namespace:
                      type: string
                      description: The namespace associated with a [product](/docs/rest-catalog/products/metafields) or [product variant](/docs/rest-catalog/product-variants/metafields) metafields. You should save a metafield namespace under this format `shipping_carrier_{yourCarrierId}`; otherwise, you will not be able to recognize it as an attribute.
                    resource_type:
                      type: string
                      enum:
                      - product
                      - variant
                      description: Resource type associated with the meta field. Currently, the only values available are 'product' or 'variant'.
                    resource_id:
                      type: string
                      description: The resource ID of the meta field.
                    attribute_type:
                      type: string
                      enum:
                      - metafield
                      description: Attribute type associated with the product or product variant meta field. Currently, the only value for this is 'metafield'.
        customer:
          type: object
          title: Customer Details
          description: The details of the Customer that has made the purchase.
          properties:
            customer_groups:
              type: array
              items:
                type: object
                title: Customer Group
                description: The Group (if any) that this customer is in. This will default to zero if the customer is not in a group or is a guest.
                properties:
                  customer_group_id:
                    type: integer
                  customer_group_name:
                    type: string
            customer_id:
              type: integer
        store_id:
          type: string
        request_context:
          type: object
          title: Request Context
          description: A collection of Reference Value objects.
          properties:
            reference_values:
              type: array
              items:
                type: object
                title: Reference Value
                description: Value objects contained within the request context.
                properties:
                  name:
                    type: string
                    description: The property to which the reference value pertains. Examples include `channel_id` and `cart_id`.
                  value:
                    type: string
      required:
      - origin
      - destination
      - items
      - store_id
    ZoneOptionsInstance:
      type: object
      description: Any zone-specific request options declared by the carrier and configured by the merchant to retrieve rates. Optional.
      title: Zone Options Instance
      x-internal: false
    ConnectionOptionsInstance:
      type: object
      description: Any global request options declared by the carrier and configured by the merchant to retrieve rates. Optional.
      title: Connection Options Instance
      x-internal: false
    FormFieldValue:
      type: string
      description: The value of a [shipping address](/docs/rest-management/orders/order-shipping-addresses#get-a-shipping-address) form field. Depending on the form field, this could be a user-defined value or the value of a hidden input.
      title: Form Field Value
    CheckConnectionOptionsResponsePayload:
      type: object
      properties:
        valid:
          type: boolean
          description: Indicates whether or not the connection options are valid.
        messages:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
                minLength: 1
                maxLength: 500
              type:
                type: string
                enum:
                - INFO
                - WARNING
                - ERROR
            required:
            - text
            - type
            title: Message
            description: A simple string/type response for returning information.
      title: Check Connection Options Response Payload
      description: The response received back from the Shipping Provider connection check. This allows the store to understand whether the connection was successful.
      x-internal: false
  securitySchemes:
    X-Auth-Token:
      name: X-Auth-Token
      description: '### OAuth scopes


        | UI Name | Permission | Parameter |

        |:--|:--|:-|

        | Information & Settings  | read-only  | `store_v2_information_read_only`|

        | Information & Settings  | modify     | `store_v2_information`          |


        ### Authentication header


        | Header | Argument | Description |

        |:-|:|:|

        | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). |


        ###

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/bigcommerce-shipping-provider-api-openapi.yml