{"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.\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.","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. \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.","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.\n\nOptional fields must be omitted from the response when no value is available.\n","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.\n\nEach 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"}}}}