{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/bigcommerce/main/json-schema/bigcommerce-rate-request-payload-schema.json", "title": "Rate Request Payload", "description": "Payload sent to a Shipping Provider to get quotes.", "x-generated": "2026-10-12", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/bigcommerce-shipping-provider-api-openapi.yml#/components/schemas/RateRequestPayload", "type": "object", "properties": { "base_options": { "$ref": "#/$defs/BaseOptions" }, "zone_options": { "$ref": "#/$defs/ZoneOptionsInstance" }, "connection_options": { "$ref": "#/$defs/ConnectionOptionsInstance" } }, "required": [ "base_options" ], "x-internal": false, "$defs": { "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 }, "city": { "type": "string", "maxLength": 50 }, "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 }, "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 }, "city": { "type": "string", "maxLength": 50 }, "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 }, "address_type": { "description": "Defaults to residential. Optional.", "type": "string", "enum": [ "RESIDENTIAL", "COMMERCIAL" ] }, "form_fields": { "type": "object", "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": { "
": { "$ref": "#/$defs/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" ] }, "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" }, "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 } } }