openapi: 3.1.0
info:
  title: 'Integrations: Shipping Provider'
  version: 1.0.0
paths:
  /rate:
    post:
      operationId: requestShippingRates
      summary: Request Shipping Rates
      description: >-
        Request shipping rates. BigCommerce sends a request for shipping quotes to the shipping provider URL. The
        shipping provider responds with shipping quotes.


        > #### Note

        > * Substitute the host and path specific to the shipping provider for `your_app.example.com` and `rate`. 

        > * The Send a Test Request feature is not currently supported for this endpoint.
      tags:
        - shippingProvider
      responses:
        '200':
          description: Quote response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateResponsePayload'
      requestBody:
        description: Rate request object.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RateRequestPayload'
  /check_connection_options:
    post:
      operationId: validateConnectionOptions
      summary: Validate Connection Options
      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. 


        > #### Note

        > * Substitute the host and path specific to the shipping provider for `your_app.example.com` and
        `check_connection_options`.  

        > * The Send a Test Request feature is not currently supported for this endpoint.
      tags:
        - shippingProvider
      responses:
        '200':
          description: Check connection options response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckConnectionOptionsResponsePayload'
      requestBody:
        description: Check connection options request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckConnectionOptionsRequestPayload'
servers:
  - url: https://your_app.example.com
    description: The public URL of your shipping provider application.
components:
  schemas:
    BaseOptionsOriginAddressType:
      type: string
      enum:
        - RESIDENTIAL
        - COMMERCIAL
      description: Optional. Defaults to `RESIDENTIAL`.
      title: BaseOptionsOriginAddressType
    BaseOptionsOrigin:
      type: object
      properties:
        street_1:
          type: string
        street_2:
          type: string
        zip:
          type: string
        city:
          type: string
        state_iso2:
          type: string
          description: State in ISO_3166 2 format.
        country_iso2:
          type: string
          description: Country in ISO_3166 2 format.
        address_type:
          $ref: '#/components/schemas/BaseOptionsOriginAddressType'
          description: Optional. Defaults to `RESIDENTIAL`.
      required:
        - zip
        - country_iso2
      description: Object representing a destination or origin address for items.
      title: BaseOptionsOrigin
    BaseOptionsDestinationAddressType:
      type: string
      enum:
        - RESIDENTIAL
        - COMMERCIAL
      description: Defaults to residential. Optional.
      title: BaseOptionsDestinationAddressType
    FormFieldValue:
      type: object
      properties:
        id:
          type: string
          description: The global ID of the shipping address form field.
        value:
          type: string
          description: >-
            The form field value. Depending on the form field, this could be a user-defined value or the value of a
            hidden input.
      description: >-
        The value of a [shipping
        address](/developer/api-reference/rest/admin/management/orders/order-shipping-addresses/get-order-shipping-address)
        form field.
      title: FormFieldValue
    BaseOptionsDestination:
      type: object
      properties:
        street_1:
          type: string
        street_2:
          type: string
        zip:
          type: string
        city:
          type: string
        state_iso2:
          type: string
          description: State in ISO_3166 2 format
        country_iso2:
          type: string
          description: Country in ISO_3166 2 format
        address_type:
          $ref: '#/components/schemas/BaseOptionsDestinationAddressType'
          description: Defaults to residential. Optional.
        form_fields:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FormFieldValue'
          description: >-
            Describes one or more [custom form fields](/developer/api-reference/rest/storefront/form-fields). Property
            key is the global ID of a shipping address form field. When no custom fields exist, the object is empty.
      required:
        - zip
        - country_iso2
      description: Object representing a destination or origin address for items.
      title: BaseOptionsDestination
    BaseOptionsItemsItemsLengthUnits:
      type: string
      enum:
        - cm
        - in
      title: BaseOptionsItemsItemsLengthUnits
    BaseOptionsItemsItemsLength:
      type: object
      properties:
        units:
          $ref: '#/components/schemas/BaseOptionsItemsItemsLengthUnits'
        value:
          type: number
          format: double
      required:
        - units
        - value
      description: Value object for a length measurement.
      title: BaseOptionsItemsItemsLength
    BaseOptionsItemsItemsWidthUnits:
      type: string
      enum:
        - cm
        - in
      title: BaseOptionsItemsItemsWidthUnits
    BaseOptionsItemsItemsWidth:
      type: object
      properties:
        units:
          $ref: '#/components/schemas/BaseOptionsItemsItemsWidthUnits'
        value:
          type: number
          format: double
      required:
        - units
        - value
      description: Value object for a length measurement.
      title: BaseOptionsItemsItemsWidth
    BaseOptionsItemsItemsHeightUnits:
      type: string
      enum:
        - cm
        - in
      title: BaseOptionsItemsItemsHeightUnits
    BaseOptionsItemsItemsHeight:
      type: object
      properties:
        units:
          $ref: '#/components/schemas/BaseOptionsItemsItemsHeightUnits'
        value:
          type: number
          format: double
      required:
        - units
        - value
      description: Value object for a length measurement.
      title: BaseOptionsItemsItemsHeight
    BaseOptionsItemsItemsWeightUnits:
      type: string
      enum:
        - oz
        - g
      title: BaseOptionsItemsItemsWeightUnits
    BaseOptionsItemsItemsWeight:
      type: object
      properties:
        units:
          $ref: '#/components/schemas/BaseOptionsItemsItemsWeightUnits'
        value:
          type: number
          format: double
      required:
        - units
        - value
      description: Value object for a weight measurement.
      title: BaseOptionsItemsItemsWeight
    BaseOptionsItemsItemsDiscountedPrice:
      type: object
      properties:
        currency:
          type: string
        amount:
          type: number
          format: double
      required:
        - currency
        - amount
      description: Value object for a money amount.
      title: BaseOptionsItemsItemsDiscountedPrice
    BaseOptionsItemsItemsDeclaredValue:
      type: object
      properties:
        currency:
          type: string
        amount:
          type: number
          format: double
      required:
        - currency
        - amount
      description: Value object for a money amount.
      title: BaseOptionsItemsItemsDeclaredValue
    BaseOptionsItemsItemsAttributesItemsResourceType:
      type: string
      enum:
        - product
        - variant
      description: Resource type associated with the meta field. Currently, the only values available are 'product' or 'variant'.
      title: BaseOptionsItemsItemsAttributesItemsResourceType
    BaseOptionsItemsItemsAttributesItemsAttributeType:
      type: string
      enum:
        - metafield
      description: >-
        Attribute type associated with the product or product variant meta field. Currently, the only value for this is
        'metafield'.
      title: BaseOptionsItemsItemsAttributesItemsAttributeType
    BaseOptionsItemsItemsAttributesItems:
      type: object
      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](/developer/api-reference/rest/admin/catalog/products/metafields)
            or [product variant](/developer/api-reference/rest/admin/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:
          $ref: '#/components/schemas/BaseOptionsItemsItemsAttributesItemsResourceType'
          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:
          $ref: '#/components/schemas/BaseOptionsItemsItemsAttributesItemsAttributeType'
          description: >-
            Attribute type associated with the product or product variant meta field. Currently, the only value for this
            is 'metafield'.
      title: BaseOptionsItemsItemsAttributesItems
    BaseOptionsItemsItems:
      type: object
      properties:
        sku:
          type: string
          description: The variant SKU.
        variant_id:
          type: string
        product_id:
          type: string
        name:
          type: string
        length:
          $ref: '#/components/schemas/BaseOptionsItemsItemsLength'
          description: Value object for a length measurement.
        width:
          $ref: '#/components/schemas/BaseOptionsItemsItemsWidth'
          description: Value object for a length measurement.
        height:
          $ref: '#/components/schemas/BaseOptionsItemsItemsHeight'
          description: Value object for a length measurement.
        weight:
          $ref: '#/components/schemas/BaseOptionsItemsItemsWeight'
          description: Value object for a weight measurement.
        discounted_price:
          $ref: '#/components/schemas/BaseOptionsItemsItemsDiscountedPrice'
          description: Value object for a money amount.
        declared_value:
          $ref: '#/components/schemas/BaseOptionsItemsItemsDeclaredValue'
          description: Value object for a money amount.
        quantity:
          type: integer
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/BaseOptionsItemsItemsAttributesItems'
          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.
      description: A cart item along with its shipping-specific attributes.
      title: BaseOptionsItemsItems
    BaseOptionsCustomerCustomerGroupsItems:
      type: object
      properties:
        customer_group_id:
          type: integer
        customer_group_name:
          type: string
      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.
      title: BaseOptionsCustomerCustomerGroupsItems
    BaseOptionsCustomer:
      type: object
      properties:
        customer_groups:
          type: array
          items:
            $ref: '#/components/schemas/BaseOptionsCustomerCustomerGroupsItems'
        customer_id:
          type: integer
      description: The details of the Customer that has made the purchase.
      title: BaseOptionsCustomer
    BaseOptionsRequestContextReferenceValuesItems:
      type: object
      properties:
        name:
          type: string
          description: The property to which the reference value pertains. Examples include `channel_id` and `cart_id`.
        value:
          type: string
      description: Value objects contained within the request context.
      title: BaseOptionsRequestContextReferenceValuesItems
    BaseOptionsRequestContext:
      type: object
      properties:
        reference_values:
          type: array
          items:
            $ref: '#/components/schemas/BaseOptionsRequestContextReferenceValuesItems'
      description: A collection of Reference Value objects.
      title: BaseOptionsRequestContext
    BaseOptions:
      type: object
      properties:
        origin:
          $ref: '#/components/schemas/BaseOptionsOrigin'
          description: Object representing a destination or origin address for items.
        destination:
          $ref: '#/components/schemas/BaseOptionsDestination'
          description: Object representing a destination or origin address for items.
        items:
          type: array
          items:
            $ref: '#/components/schemas/BaseOptionsItemsItems'
        customer:
          $ref: '#/components/schemas/BaseOptionsCustomer'
          description: The details of the Customer that has made the purchase.
        store_id:
          type: string
        request_context:
          $ref: '#/components/schemas/BaseOptionsRequestContext'
          description: A collection of Reference Value objects.
      required:
        - origin
        - destination
        - items
        - store_id
      description: The minimum required payload that is sent to retrieve rates.
      title: BaseOptions
    ZoneOptionsInstance:
      type: object
      properties: {}
      description: >-
        Any zone-specific request options declared by the carrier and configured by the merchant to retrieve rates.
        Optional.
      title: ZoneOptionsInstance
    ConnectionOptionsInstance:
      type: object
      properties: {}
      description: Any global request options declared by the carrier and configured by the merchant to retrieve rates. Optional.
      title: ConnectionOptionsInstance
    RateRequestPayload:
      type: object
      properties:
        base_options:
          $ref: '#/components/schemas/BaseOptions'
        zone_options:
          $ref: '#/components/schemas/ZoneOptionsInstance'
        connection_options:
          $ref: '#/components/schemas/ConnectionOptionsInstance'
      required:
        - base_options
      description: Payload sent to a Shipping Provider to get quotes.
      title: RateRequestPayload
    RateResponsePayloadMessagesItemsType:
      type: string
      enum:
        - INFO
        - WARNING
        - ERROR
      title: RateResponsePayloadMessagesItemsType
    RateResponsePayloadMessagesItems:
      type: object
      properties:
        text:
          type: string
        type:
          $ref: '#/components/schemas/RateResponsePayloadMessagesItemsType'
      required:
        - text
        - type
      description: A simple string/type response for returning information.
      title: RateResponsePayloadMessagesItems
    RateResponsePayloadCarrierQuotesItemsCarrierInfo:
      type: object
      properties:
        code:
          type: string
        display_name:
          type: string
      required:
        - code
        - display_name
      title: RateResponsePayloadCarrierQuotesItemsCarrierInfo
    RateResponsePayloadCarrierQuotesItemsQuotesItemsCost:
      type: object
      properties:
        currency:
          type: string
        amount:
          type: number
          format: double
      required:
        - currency
        - amount
      description: Value object for a money amount.
      title: RateResponsePayloadCarrierQuotesItemsQuotesItemsCost
    RateResponsePayloadCarrierQuotesItemsQuotesItemsMessagesItemsType:
      type: string
      enum:
        - INFO
        - WARNING
        - ERROR
      title: RateResponsePayloadCarrierQuotesItemsQuotesItemsMessagesItemsType
    RateResponsePayloadCarrierQuotesItemsQuotesItemsMessagesItems:
      type: object
      properties:
        text:
          type: string
        type:
          $ref: '#/components/schemas/RateResponsePayloadCarrierQuotesItemsQuotesItemsMessagesItemsType'
      required:
        - text
        - type
      description: A simple string/type response for returning information.
      title: RateResponsePayloadCarrierQuotesItemsQuotesItemsMessagesItems
    RateResponsePayloadCarrierQuotesItemsQuotesItemsDiscountedCost:
      type: object
      properties:
        currency:
          type: string
        amount:
          type: number
          format: double
      required:
        - currency
        - amount
      description: Value object for a money amount. Optional field; merchants may request features.
      title: RateResponsePayloadCarrierQuotesItemsQuotesItemsDiscountedCost
    RateResponsePayloadCarrierQuotesItemsQuotesItemsTransitTimeUnits:
      type: string
      enum:
        - BUSINESS_DAYS
        - DAYS
        - HOURS
      title: RateResponsePayloadCarrierQuotesItemsQuotesItemsTransitTimeUnits
    RateResponsePayloadCarrierQuotesItemsQuotesItemsTransitTime:
      type: object
      properties:
        units:
          $ref: '#/components/schemas/RateResponsePayloadCarrierQuotesItemsQuotesItemsTransitTimeUnits'
        duration:
          type: integer
      description: Value object for the length of time in transit.
      title: RateResponsePayloadCarrierQuotesItemsQuotesItemsTransitTime
    RateResponsePayloadCarrierQuotesItemsQuotesItems:
      type: object
      properties:
        code:
          type: string
          description: A code describing the service.
        display_name:
          type: string
          description: A display name for the service.
        cost:
          $ref: '#/components/schemas/RateResponsePayloadCarrierQuotesItemsQuotesItemsCost'
          description: Value object for a money amount.
        messages:
          type: array
          items:
            $ref: '#/components/schemas/RateResponsePayloadCarrierQuotesItemsQuotesItemsMessagesItems'
        description:
          type: string
        rate_id:
          type: string
        discounted_cost:
          $ref: '#/components/schemas/RateResponsePayloadCarrierQuotesItemsQuotesItemsDiscountedCost'
          description: Value object for a money amount. Optional field; merchants may request features.
        dispatch_date:
          type: string
          format: date
          description: >-
            Date at which carrier dispatches to the shipping destination. Optional field; merchants may request
            features.
        transit_time:
          $ref: '#/components/schemas/RateResponsePayloadCarrierQuotesItemsQuotesItemsTransitTime'
          description: Value object for the length of time in transit.
      required:
        - code
        - display_name
        - cost
      description: |
        A quote being returned as part of the rate request.

        Optional fields must be omitted from the response when no value is available.
      title: RateResponsePayloadCarrierQuotesItemsQuotesItems
    RateResponsePayloadCarrierQuotesItems:
      type: object
      properties:
        carrier_info:
          $ref: '#/components/schemas/RateResponsePayloadCarrierQuotesItemsCarrierInfo'
        quotes:
          type: array
          items:
            $ref: '#/components/schemas/RateResponsePayloadCarrierQuotesItemsQuotesItems'
      required:
        - quotes
      description: A grouping of carrier rates and optionally, info about that carrier.
      title: RateResponsePayloadCarrierQuotesItems
    RateResponsePayload:
      type: object
      properties:
        quote_id:
          type: string
        ttl:
          type: integer
          description: Time-to-live (TTL) in seconds
        messages:
          type: array
          items:
            $ref: '#/components/schemas/RateResponsePayloadMessagesItems'
        carrier_quotes:
          type: array
          items:
            $ref: '#/components/schemas/RateResponsePayloadCarrierQuotesItems'
      required:
        - quote_id
        - messages
        - carrier_quotes
      description: The response from the Shipping Service. Contains zero or more quotes.
      title: RateResponsePayload
    CheckConnectionOptionsRequestPayload:
      type: object
      properties:
        connection_options:
          $ref: '#/components/schemas/ConnectionOptionsInstance'
      required:
        - connection_options
      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.
      title: CheckConnectionOptionsRequestPayload
    CheckConnectionOptionsResponsePayloadMessagesItemsType:
      type: string
      enum:
        - INFO
        - WARNING
        - ERROR
      title: CheckConnectionOptionsResponsePayloadMessagesItemsType
    CheckConnectionOptionsResponsePayloadMessagesItems:
      type: object
      properties:
        text:
          type: string
        type:
          $ref: '#/components/schemas/CheckConnectionOptionsResponsePayloadMessagesItemsType'
      required:
        - text
        - type
      description: A simple string/type response for returning information.
      title: CheckConnectionOptionsResponsePayloadMessagesItems
    CheckConnectionOptionsResponsePayload:
      type: object
      properties:
        valid:
          type: boolean
          description: Indicates whether or not the connection options are valid.
        messages:
          type: array
          items:
            $ref: '#/components/schemas/CheckConnectionOptionsResponsePayloadMessagesItems'
      description: >-
        The response received back from the Shipping Provider connection check. This allows the store to understand
        whether the connection was successful.
      title: CheckConnectionOptionsResponsePayload
