Shipping Providers
Implement endpoints consumed by BigCommerce for custom shipping integrations. To learn more, see Shipping Provider API Overview.
Authentication
This specification file describes API requests BigCommerce will make to a registered shipping carrierʼs server to check connection options and retrieve rates. As such, the method of authentication is determined by the carrier server.
For more, see developer-configured authentication for provider APIs.
Subresources
Check Connection Options
The Check Connection Options request is made by BigCommerce when checking for available shipping options. Each Shipping Provider will have different configurations for the payload.
Rate
The Rate request is made by BigCommerce to get shipping quotes from the provider.
Additional Information
Webhooks
Related API Resources
Request shipping rates
POST /rate
Request
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.comandrate. - The Send a Test Request feature is not currently supported for this endpoint.
Parameters
- app_domain in path - string
Rate request object.
Body
Payload sent to a Shipping Provider to get quotes.
base_optionsobject
requiredThe minimum required payload that is sent to retrieve rates.
zone_optionsobject
Any zone-specific request options declared by the carrier and configured by the merchant to retrieve rates. Optional.
connection_optionsobject
Any global request options declared by the carrier and configured by the merchant to retrieve rates. Optional.
example
{ "base_options": { "origin": { "street_1": "string", "street_2": "string", "zip": "94105", "city": "San Francisco", "state_iso2": "st", "country_iso2": "US", "address_type": "RESIDENTIAL" }, "destination": { "street_1": "string", "street_2": "string", "zip": "94105", "city": "San Francisco", "state_iso2": "st", "country_iso2": "US", "address_type": "RESIDENTIAL", "form_fields": { "1": "selected_value", "3": "checkbox_selection_1" } }, "items": [ { "sku": "string", "variant_id": "string", "product_id": "string", "name": "string", "length": { "units": "cm", "value": 0 }, "width": { "units": "cm", "value": 0 }, "height": { "units": "cm", "value": 0 }, "weight": { "units": "oz", "value": 0 }, "discounted_price": { "currency": "string", "amount": 0 }, "declared_value": { "currency": "string", "amount": 0 }, "quantity": 0, "attributes": [ { "key": "string", "value": "string", "namespace": "string", "resource_type": "product", "resource_id": "string", "attribute_type": "metafield" } ] } ], "customer": { "customer_groups": [ { "customer_group_id": 0, "customer_group_name": "string" } ], "customer_id": 0 }, "store_id": "string", "request_context": { "reference_values": [ { "name": "string", "value": "string" } ] } }, "zone_options": {}, "connection_options": {} }
Response
Quote response.
Body
The response from the Shipping Service. Contains zero or more quotes.
quote_idstring
required<= 50 charactersmessagesarray[object]
requiredcarrier_quotesarray[object]
required
With shipping rates
{ "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
{ "quote_id": "example_quote", "messages": [], "carrier_quotes": [] }
Validate connection options
POST /check_connection_options
Request
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.comandcheck_connection_options. - The Send a Test Request feature is not currently supported for this endpoint.
Parameters
- app_domain in path - string
Check connection options request.
Body
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.
connection_optionsobject
requiredAny global request options declared by the carrier and configured by the merchant to retrieve rates. Optional.
example
{ "connection_options": {} }
Response
Check connection options response.
Body
The response received back from the Shipping Provider connection check. This allows the store to understand whether the connection was successful.
validboolean
Indicates whether or not the connection options are valid.
messagesarray[object]
response
{ "valid": true, "messages": [ { "text": "adipi", "type": "WARNING" }, { "text": "nu", "type": "WARNING" }, { "text": "an", "type": "INFO" } ] }