openapi: 3.1.0
info:
  title: 'Admin Management: Shipping V3'
  version: 1.0.0
paths:
  /stores/{store_hash}/v3/shipping/products/customs-information:
    get:
      operationId: getCustomsInformation
      summary: List Customs Information
      description: >-
        Get customs information for products.


        This list can be filtered to return customs information objects specific to a list of requested product_ids.
        This is achieved by appending the query string `?product_id:in=4,5,6` to the resource
        `/shipping/products/customs-information`.


        ```http

        GET /shipping/products/customs-information?product_id:in=4,5,6

        ```
      tags:
        - customsInformation
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: product_id:in
          in: query
          description: >-
            A comma-separated list of product IDs. For more information, see
            [Filtering](/developer/api-reference/rest/overview#filtering).
          required: false
          schema:
            type: array
            items:
              type: integer
        - name: page
          in: query
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          required: false
          schema:
            type: integer
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

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

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### 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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customs Information_getCustomsInformation_Response_200'
    put:
      operationId: updateCustomsInformation
      summary: Upsert Customs Information
      description: >-
        Creates and updates product customs information.


        This is a batch operation where the creation of multiple customs information objects can be done with one `PUT`
        request.


        **Limits**

        * Limit of 50 customs information objects per `PUT` request.
      tags:
        - customsInformation
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

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

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### 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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customs Information_updateCustomsInformation_Response_200'
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/customsInformation_request'
    delete:
      operationId: deleteCustomsInformation
      summary: Delete Customs Information
      description: |-
        Deletes customs information objects for a product.

        ## Example

        This is a batch operation. The `product_id:in` query parameter is required.

        ```http
        DELETE /shipping/products/customs-information?product_id:in=4,5,6
        ```
      tags:
        - customsInformation
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: product_id:in
          in: query
          required: true
          schema:
            type: array
            items:
              type: integer
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

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

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### 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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '204':
          description: No Content
          content:
            application/json:
              schema:
                type: object
                properties: {}
  /stores/{store_hash}/v3/shipping/settings:
    get:
      operationId: getShippingSettings
      summary: Get Shipping Settings
      description: Returns the global-level shipping settings.
      tags:
        - shippingSettings
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

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

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### 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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipping Settings_getShippingSettings_Response_200'
    put:
      operationId: updateShippingSettings
      summary: Update Shipping Settings
      description: Updates the global-level shipping settings.
      tags:
        - shippingSettings
      parameters:
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

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

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### 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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipping Settings_updateShippingSettings_Response_200'
        '400':
          description: Bad Request. Input is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateShippingSettingsRequestBadRequestError'
        '422':
          description: The request body does not meet the specification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateShippingSettingsRequestUnprocessableEntityError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/shippingSettings'
  /stores/{store_hash}/v3/shipping/settings/channels/{channel_id}:
    get:
      operationId: getChannelShippingSettings
      summary: Get Shipping Settings per Channel
      description: Returns shipping settings for a specific channel.
      tags:
        - shippingSettings
      parameters:
        - name: channel_id
          in: path
          description: Channel ID
          required: true
          schema:
            type: string
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

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

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### 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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipping Settings_getChannelShippingSettings_Response_200'
    put:
      operationId: updateChannelShippingSettings
      summary: Update Shipping Settings per Channel
      description: Updates shipping settings for a specific channel.
      tags:
        - shippingSettings
      parameters:
        - name: channel_id
          in: path
          description: Channel ID
          required: true
          schema:
            type: string
        - name: store_hash
          in: path
          description: Permanent ID of the BigCommerce store.
          required: true
          schema:
            type: string
        - name: X-Auth-Token
          in: header
          description: >-
            ### OAuth scopes


            | UI Name | Permission | Parameter |

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

            |  Products | modify | `store_v2_products` |

            |  Products | read-only | `store_v2_products_read_only` |


            ### 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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


            ### Further reading


            For example requests and more information about authenticating BigCommerce APIs, see [Authentication and
            Example
            Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


            For more about BigCommerce OAuth scopes, see our [Guide to API
            Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


            For a list of API status codes, see [API Status
            Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
          required: true
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response
            body.
          required: true
          schema:
            type: string
            default: application/json
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shipping Settings_updateChannelShippingSettings_Response_200'
        '400':
          description: Bad Request. Input is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateChannelShippingSettingsRequestBadRequestError'
        '422':
          description: The request body does not meet the specification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateChannelShippingSettingsRequestUnprocessableEntityError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/channelShippingSettings'
servers:
  - url: https://api.bigcommerce.com
    description: https://api.bigcommerce.com
components:
  schemas:
    harmonizedSystemCodes:
      type: object
      properties: {}
      description: >-
        Key-value pairs that are commonly used in the following form:  


        `countryISO2: '/^[0-9A-Za-z]{6,14}$/'`


        This key-value pair represents a country and the associated `hs_code` that applies to that country. 


        You can also use the `ALL` key in place of an ISO2 key to specify that the `hs_code` applies to all countries.
        The `ALL` key can be combined with other countries in the `hs_code` object.
      title: harmonizedSystemCodes
    customsInformation:
      type: object
      properties:
        product_id:
          type: integer
          description: The ID of the product which the customs information data will apply to.
        country_of_origin:
          type: string
          description: The country of manufacture, production, or growth represented in ISO 3166-1 alpha-2 format.
        commodity_description:
          type: string
          description: >-
            Description that provides information for customs to identify and verify shapes physical characteristics and
            packaging of each shipment.
        international_shipping:
          type: boolean
          description: Flag to determine whether this product will be shipped internationally.
        hs_codes:
          $ref: '#/components/schemas/harmonizedSystemCodes'
        created_at:
          type: string
          format: date-time
          description: Date and time when the customs information was created.
        updated_at:
          type: string
          format: date-time
          description: Date and time when the customs information was last updated.
      description: Data about the customs information object.
      title: customsInformation
    MetaCollectionPaginationLinks:
      type: object
      properties:
        previous:
          type: string
          description: Query string appended to the resource to return to the previous page.
        next:
          type: string
          description: Query string appended to the resource to proceed to the next page.
        current:
          type: string
          description: Query string appended to the resource to show the current page.
      title: MetaCollectionPaginationLinks
    MetaCollectionPagination:
      type: object
      properties:
        total:
          type: integer
          description: Total number of items returned.
        count:
          type: integer
          description: Number of items returned on per page.
        per_page:
          type: integer
          description: Number of items to be displayed per page.
        current_page:
          type: integer
          description: Current page number.
        total_page:
          type: integer
          description: Total number of pages.
        links:
          $ref: '#/components/schemas/MetaCollectionPaginationLinks'
      title: MetaCollectionPagination
    metaCollection:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/MetaCollectionPagination'
      description: Meta data relating to pagination.
      title: metaCollection
    Customs Information_getCustomsInformation_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/customsInformation'
        meta:
          $ref: '#/components/schemas/metaCollection'
      title: Customs Information_getCustomsInformation_Response_200
    customsInformation_request:
      type: object
      properties:
        product_id:
          type: integer
          description: The product ID to which the customs information data applies.
        country_of_origin:
          type: string
          description: The country of manufacture, production, or growth represented in ISO 3166-1 alpha-2 format.
        commodity_description:
          type: string
          description: >-
            Description that provides information for customs to identify and verify the shapes, physical
            characteristics, and packaging of each shipment.
        international_shipping:
          type: boolean
          description: Flag to determine whether this product will be shipped internationally.
        hs_codes:
          $ref: '#/components/schemas/harmonizedSystemCodes'
      required:
        - product_id
        - country_of_origin
        - commodity_description
        - international_shipping
        - hs_codes
      description: Data about the customs information object.
      title: customsInformation_request
    Customs Information_updateCustomsInformation_Response_200:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/customsInformation'
      title: Customs Information_updateCustomsInformation_Response_200
    ShippingSettingsCheckoutCountryListStrategy:
      type: string
      enum:
        - DISPLAY_ALL_COUNTRIES
        - DISPLAY_ONLY_SHIPPABLE_COUNTRIES
      description: The approach for displaying the list of countries at checkout.
      title: ShippingSettingsCheckoutCountryListStrategy
    ShippingSettingsCheckout:
      type: object
      properties:
        country_list_strategy:
          $ref: '#/components/schemas/ShippingSettingsCheckoutCountryListStrategy'
          description: The approach for displaying the list of countries at checkout.
        out_of_delivery_zone_message:
          type: string
          description: >-
            Message shown to the shopper during checkout when their order does not meet the merchant's shipping
            criteria.
      title: ShippingSettingsCheckout
    shippingSettings:
      type: object
      properties:
        checkout:
          $ref: '#/components/schemas/ShippingSettingsCheckout'
      title: shippingSettings
    ShippingSettingsGetResponsesContentApplicationJsonSchemaMeta:
      type: object
      properties: {}
      title: ShippingSettingsGetResponsesContentApplicationJsonSchemaMeta
    Shipping Settings_getShippingSettings_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/shippingSettings'
        meta:
          $ref: '#/components/schemas/ShippingSettingsGetResponsesContentApplicationJsonSchemaMeta'
      title: Shipping Settings_getShippingSettings_Response_200
    ShippingSettingsPutResponsesContentApplicationJsonSchemaMeta:
      type: object
      properties: {}
      title: ShippingSettingsPutResponsesContentApplicationJsonSchemaMeta
    Shipping Settings_updateShippingSettings_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/shippingSettings'
        meta:
          $ref: '#/components/schemas/ShippingSettingsPutResponsesContentApplicationJsonSchemaMeta'
      title: Shipping Settings_updateShippingSettings_Response_200
    UpdateShippingSettingsRequestBadRequestError:
      type: object
      properties:
        status:
          type: number
          format: double
        title:
          type: string
        type:
          type: string
        detail:
          type: string
      title: UpdateShippingSettingsRequestBadRequestError
    UpdateShippingSettingsRequestUnprocessableEntityError:
      type: object
      properties:
        status:
          type: number
          format: double
        title:
          type: string
        type:
          type: string
      title: UpdateShippingSettingsRequestUnprocessableEntityError
    ChannelShippingSettingsCheckout:
      type: object
      properties:
        out_of_delivery_zone_message:
          type: string
          description: >-
            Message shown to the shopper during checkout when their order does not meet the merchant's shipping
            criteria.
      title: ChannelShippingSettingsCheckout
    channelShippingSettings:
      type: object
      properties:
        checkout:
          $ref: '#/components/schemas/ChannelShippingSettingsCheckout'
      title: channelShippingSettings
    ShippingSettingsChannelsChannelIdGetResponsesContentApplicationJsonSchemaMeta:
      type: object
      properties: {}
      title: ShippingSettingsChannelsChannelIdGetResponsesContentApplicationJsonSchemaMeta
    Shipping Settings_getChannelShippingSettings_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/channelShippingSettings'
        meta:
          $ref: '#/components/schemas/ShippingSettingsChannelsChannelIdGetResponsesContentApplicationJsonSchemaMeta'
      title: Shipping Settings_getChannelShippingSettings_Response_200
    ShippingSettingsChannelsChannelIdPutResponsesContentApplicationJsonSchemaMeta:
      type: object
      properties: {}
      title: ShippingSettingsChannelsChannelIdPutResponsesContentApplicationJsonSchemaMeta
    Shipping Settings_updateChannelShippingSettings_Response_200:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/channelShippingSettings'
        meta:
          $ref: '#/components/schemas/ShippingSettingsChannelsChannelIdPutResponsesContentApplicationJsonSchemaMeta'
      title: Shipping Settings_updateChannelShippingSettings_Response_200
    UpdateChannelShippingSettingsRequestBadRequestError:
      type: object
      properties:
        status:
          type: number
          format: double
        title:
          type: string
        type:
          type: string
        detail:
          type: string
      title: UpdateChannelShippingSettingsRequestBadRequestError
    UpdateChannelShippingSettingsRequestUnprocessableEntityError:
      type: object
      properties:
        status:
          type: number
          format: double
        title:
          type: string
        type:
          type: string
      title: UpdateChannelShippingSettingsRequestUnprocessableEntityError
  securitySchemes:
    X-Auth-Token:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: >-
        ### OAuth scopes


        | UI Name | Permission | Parameter |

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

        |  Products | modify | `store_v2_products` |

        |  Products | read-only | `store_v2_products_read_only` |


        ### 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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). |


        ### Further reading


        For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example
        Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests).


        For more about BigCommerce OAuth scopes, see our [Guide to API
        Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes).


        For a list of API status codes, see [API Status
        Codes](/developer/api-reference/rest/overview#rest-http-status-codes).
