BigCommerce Shipping Providers is a service that offers a range of shipping solutions for online retailers using the BigCommerce platform. By partnering with various shipping carriers, they are able to offer competitive rates and reliable delivery options to help businesses streamline their shipping processes.
openapi: 3.0.0
info:
version: ''
title: BigCommerce Shipping Providers
description: >-
Implement endpoints consumed by BigCommerce for custom shipping
integrations. To learn more, see [Shipping Provider API
Overview](/docs/integrations/shipping).
## 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](/docs/start/authentication#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
- [Shipments](/docs/integrations/webhooks/events#shipments)
### Related API Resources
- [Shipping Provider](/docs/rest-contracts/shipping)
- [Shipping V2 API](/docs/rest-management/shipping-v2)
termsOfService: https://www.bigcommerce.com/terms
contact:
name: BigCommerce
url: https://www.bigcommerce.com
email: [email protected]
tags:
- name: Shipping Provider
servers:
- url: https://{app_domain}
variables:
app_domain:
default: your_app.example.com
description: >-
The [URL
authority](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_URL#authority)
of your appʼs server.
description: The public URL of your shipping provider application.
paths:
/rate:
post:
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.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RateRequestPayload'
description: Rate request object.
required: true
responses:
'200':
description: Quote response.
content:
application/json:
schema:
$ref: '#/components/schemas/RateResponsePayload'
examples:
With shipping rates:
value:
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:
value:
quote_id: example_quote
messages: []
carrier_quotes: []
summary: BigCommerce Request shipping rates
tags:
- Shipping Provider
operationId: requestShippingRates
/check_connection_options:
post:
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.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CheckConnectionOptionsRequestPayload'
description: Check connection options request.
required: true
responses:
'200':
description: Check connection options response.
content:
application/json:
schema:
$ref: '#/components/schemas/CheckConnectionOptionsResponsePayload'
examples:
response:
value:
valid: true
messages:
- text: adipi
type: WARNING
- text: nu
type: WARNING
- text: an
type: INFO
summary: BigCommerce Validate connection options
tags:
- Shipping Provider
operationId: validateConnectionOptions
components:
schemas:
RateRequestPayload:
type: object
title: Rate Request Payload
description: Payload sent to a Shipping Provider to get quotes.
properties:
base_options:
$ref: '#/components/schemas/BaseOptions'
zone_options:
$ref: '#/components/schemas/ZoneOptionsInstance'
connection_options:
$ref: '#/components/schemas/ConnectionOptionsInstance'
required:
- base_options
x-internal: false
BaseOptionsSchema:
type: object
title: Base Options
description: Payload sent to a Shipping Provider in to get quotes.
properties:
base_options:
description: The minimum required payload that is sent to retrieve rates.
type: object
title: Base Rate Request
required:
- origin
- destination
- items
- store_id
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
example: '94105'
city:
type: string
maxLength: 50
example: San Francisco
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
example: US
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
example: '94105'
city:
type: string
maxLength: 50
example: San Francisco
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
example: US
address_type:
description: Optional. Defaults to `RESIDENTIAL`.
type: string
enum:
- RESIDENTIAL
- COMMERCIAL
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 width 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 height 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 metafields for
[products](/docs/rest-catalog/products/metafields#create-a-product-metafield)
and [product
variants](/docs/rest-catalog/product-variants/metafields).
Save the metafield namespace using the format
`shipping_carrier_{yourCarrierId}`; otherwise, it
will not be recognized as a valid attribute.
resource_type:
type: string
enum:
- product
- variant
description: >-
The resource type associated with the metafield.
Currently, the only values available are `product`
and `variant`.
resource_id:
type: string
description: The resource ID of the meta field.
attribute_type:
type: string
enum:
- metafield
description: >-
The attribute type associated with the product or
product variant metafield. Currently, the only value
available 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. The value
defaults 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
value:
type: string
zone_options:
$ref: '#/components/schemas/ZoneOptionsInstance'
connection_options:
$ref: '#/components/schemas/ConnectionOptionsInstance'
required:
- base_options
x-internal: false
CustomerDetails:
type: object
properties:
customer_groups:
type: array
items:
type: object
properties:
customer_group_id:
type: integer
customer_group_name:
type: string
title: Customer Group
description: >-
The Group (if any) that this customer is in. The value will
default to zero if the customer is not in a group or is a guest.
customer_id:
type: integer
title: Customer Details
description: The details of the Customer that has made the purchase.
x-internal: false
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
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
RateOptionsInstance:
description: Optional, any checkout specific request options to retrieve rates
type: array
items:
type: object
properties:
key:
type: string
value:
type: string
required:
- key
- value
title: Key Value Pair
title: Rate Options Instance
x-internal: false
CustomerGroup:
type: object
properties:
customer_group_id:
type: integer
customer_group_name:
type: string
title: Customer Group
description: >-
The Group (if any) that this customer is in. The value will default to
zero if the customer is not in a group or is a guest.
x-internal: false
KeyValuePair:
type: object
properties:
key:
type: string
value:
type: string
required:
- key
- value
title: Key Value Pair
x-internal: false
RateResponsePayload:
type: object
properties:
quote_id:
type: string
maxLength: 50
messages:
type: array
items:
type: object
properties:
text:
type: string
minLength: 1
maxLength: 500
type:
type: string
enum:
- INFO
- WARNING
- ERROR
required:
- text
- type
title: Message
description: A simple string/type response for returning information.
carrier_quotes:
type: array
items:
type: object
description: >-
A grouping of carrier rates and optionally, info about that
carrier.
properties:
carrier_info:
type: object
properties:
code:
type: string
maxLength: 50
display_name:
type: string
minLength: 1
maxLength: 100
required:
- code
- display_name
quotes:
type: array
items:
type: object
properties:
code:
description: A code describing the service.
type: string
minLength: 1
maxLength: 50
example: GND
display_name:
description: A display name for the service.
type: string
maxLength: 100
cost:
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bigcommerce/refs/heads/main/openapi/shipping-providers-openapi-original.yml