BigCommerce
Management API
Order Shipments

Orders V2

Get Order Shipments

GET /orders/{order_id}/shipments

Request

Gets a list of all shipments on an order.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • page in query - number

    The page to return in the response.

  • limit in query - number

    Number of results to return.

example

Response

Body

array | application/json
  • id
    integer

    Shipment ID.

    Example: 1

  • order_id
    integer

    ID of the order associated with this shipment.

    Example: 120

  • customer_id
    integer

    ID of this order’s customer.

    Example: 5

  • order_address_id
    integer

    ID of the desired shipping_address associated with the shipment.

    Example: 20

  • date_created
    string

    Creation date for the shipment.

  • tracking_number
    string

    Tracking number of the shipment.

    Example: w4se4b6ASFEW4T

  • shipping_method
    string

    Additional information to describe the method of shipment (ex. Standard, Ship by Weight, Custom Shipment). Can be used for live quotes from certain shipping providers. If different from shipping_provider, shipping_method should correspond to tracking_carrier.

    Example: Ship by Weight

  • shipping_provider

    Any of:

    Example: shipperhq

  • tracking_carrier
    string

    Tracking carrier for the shipment. Acceptable values for tracking_carrier include an empty string ("") or one of the valid tracking-carrier values.

    Example:

  • tracking_link
    string

    The custom tracking link supplied on POST or PUT shipments. For the auto-generated tracking link see the generated_tracking_link property.

  • comments
    string

    Comments the shipper wishes to add.

    <= 65535 characters
  • billing_address
    object

  • shipping_address
    object

    Shipping Address properties common to all requests and responses.

  • items
    array[object]

    The items in the shipment. This object has the following members, all integer: order_product_id (required), quantity (required), product_id (read-only). A sample items value might be: [ {"order_product_id":16,"product_id": 0,"quantity":2} ]

  • shipping_provider_display_name
    string

    The human-readable name for the shipping_provider.

  • generated_tracking_link
    string

    The tracking link that is generated using the combination of either the tracking_number and shipping_provider or tracking_number and tracking_carrier. This will be empty if the custom tracking_link value is provided.

application/json

Create Order Shipment

POST /orders/{order_id}/shipments

Request

Creates an Order Shipment. For more details, see Shipping an Order.

Required Fields

  • order_address_id
  • items

Usage notes

There are three methods for generating a tracking link for a shipment:

  1. Use shipping_provider and tracking_number: This generates an automatic tracking link that you can click from the BigCommerce control panel and customer-facing emails. The generated_tracking_link property in the API response represents this tracking link. The tracking_link property in the API response will remain empty.

  2. Use tracking_carrier and tracking_number: This also creates an automatic tracking link that you can click in both the BigCommerce control panel and customer-facing emails. Like the previous method, the generated_tracking_link property in the API response represents this tracking link. The tracking_link property in the API response will remain empty.

  3. Supply a custom tracking_link: By providing a value for the tracking_link property, you can use your own tracking link within the BigCommerce control panel and in customer-facing emails. The API response will return your supplied tracking link as part of the tracking_link property in the response. In situations when there isn't a generated_tracking_link, the property in the API response will remain empty.

Acceptable values for shipping_provider include the following, and this list may be updated at any time:

  • "", an empty string
  • auspost
  • `canadapost
  • endicia
  • usps
  • fedex
  • royalmail
  • ups
  • upsready
  • upsonline
  • shipperhq
  • carrier_{your_carrier_id}, when the carrier is a third-party Shipping Provider

Acceptable values for tracking_carrier include an empty string ("") or one of the valid tracking-carrier values.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string - required

    The MIME type of the request body.

Body

object | application/json
  • order_address_id
    integer

    ID of the desired shipping_address associated with the shipment.

    Example: 20

  • tracking_number
    string

    Tracking number of the shipment.

    <= 50 characters

    Example: w4se4b6ASFEW4T

  • tracking_link
    string

    The custom tracking link supplied on POST or PUT shipments. For the auto-generated tracking link see the generated_tracking_link property.

    <= 500 characters

    Example: https://www.mycustomtrackinglink.com/tracking

  • shipping_method
    string

    Additional information to describe the method of shipment (ex. Standard, Ship by Weight, Custom Shipment). Can be used for live quotes from certain shipping providers. If different from shipping_provider, shipping_method should correspond to tracking_carrier.

    Example: Ship by Weight

  • shipping_provider

    Any of:

    Example: shipperhq

  • tracking_carrier
    string

    Tracking carrier for the shipment. Acceptable values for tracking_carrier include an empty string ("") or one of the valid tracking-carrier values.

    Example:

  • comments
    string

    Comments the shipper wishes to add.

    <= 65535 characters
  • items
    array[object]

    The items in the shipment. This object has the following members, all integer: order_product_id (required), quantity (required), product_id (read-only). A sample items value might be: [ {"order_product_id":16,"product_id": 0,"quantity":2} ]

Response

Body

object | application/json
  • id
    integer

    Shipment ID.

    Example: 1

  • order_id
    integer

    ID of the order associated with this shipment.

    Example: 120

  • customer_id
    integer

    ID of this order’s customer.

    Example: 5

  • order_address_id
    integer

    ID of the desired shipping_address associated with the shipment.

    Example: 20

  • date_created
    string

    Creation date for the shipment.

  • tracking_number
    string

    Tracking number of the shipment.

    Example: w4se4b6ASFEW4T

  • shipping_method
    string

    Additional information to describe the method of shipment (ex. Standard, Ship by Weight, Custom Shipment). Can be used for live quotes from certain shipping providers. If different from shipping_provider, shipping_method should correspond to tracking_carrier.

    Example: Ship by Weight

  • shipping_provider

    Any of:

    Example: shipperhq

  • tracking_carrier
    string

    Tracking carrier for the shipment. Acceptable values for tracking_carrier include an empty string ("") or one of the valid tracking-carrier values.

    Example:

  • tracking_link
    string

    The custom tracking link supplied on POST or PUT shipments. For the auto-generated tracking link see the generated_tracking_link property.

  • comments
    string

    Comments the shipper wishes to add.

    <= 65535 characters
  • billing_address
    object

  • shipping_address
    object

    Shipping Address properties common to all requests and responses.

  • items
    array[object]

    The items in the shipment. This object has the following members, all integer: order_product_id (required), quantity (required), product_id (read-only). A sample items value might be: [ {"order_product_id":16,"product_id": 0,"quantity":2} ]

  • shipping_provider_display_name
    string

    The human-readable name for the shipping_provider.

  • generated_tracking_link
    string

    The tracking link that is generated using the combination of either the tracking_number and shipping_provider or tracking_number and tracking_carrier. This will be empty if the custom tracking_link value is provided.

application/json

Delete Order Shipments

DELETE /orders/{order_id}/shipments

Request

Deletes all shipments associated with an order.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string - required

    The MIME type of the response body.

  • order_id in path - integer - required

    ID of the order.

example

Response

Get Count of Order Shipments

GET /orders/{order_id}/shipments/count

Request

Gets a count of the number of shipments that have been made for a single order.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string - required

    The MIME type of the response body.

  • order_id in path - integer - required

    ID of the order.

example

Response

Body

object | application/json
  • count
    number

    Example: 27

response

Get a Shipment

GET /orders/{order_id}/shipments/{shipment_id}

Request

Gets an order shipment.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string - required

    The MIME type of the response body.

  • order_id in path - integer - required

    ID of the order.

  • shipment_id in path - integer - required

    Shipment ID.

example

Response

Body

object | application/json
  • id
    integer

    Shipment ID.

    Example: 1

  • order_id
    integer

    ID of the order associated with this shipment.

    Example: 120

  • customer_id
    integer

    ID of this order’s customer.

    Example: 5

  • order_address_id
    integer

    ID of the desired shipping_address associated with the shipment.

    Example: 20

  • date_created
    string

    Creation date for the shipment.

  • tracking_number
    string

    Tracking number of the shipment.

    Example: w4se4b6ASFEW4T

  • shipping_method
    string

    Additional information to describe the method of shipment (ex. Standard, Ship by Weight, Custom Shipment). Can be used for live quotes from certain shipping providers. If different from shipping_provider, shipping_method should correspond to tracking_carrier.

    Example: Ship by Weight

  • shipping_provider

    Any of:

    Example: shipperhq

  • tracking_carrier
    string

    Tracking carrier for the shipment. Acceptable values for tracking_carrier include an empty string ("") or one of the valid tracking-carrier values.

    Example:

  • tracking_link
    string

    The custom tracking link supplied on POST or PUT shipments. For the auto-generated tracking link see the generated_tracking_link property.

  • comments
    string

    Comments the shipper wishes to add.

    <= 65535 characters
  • billing_address
    object

  • shipping_address
    object

    Shipping Address properties common to all requests and responses.

  • items
    array[object]

    The items in the shipment. This object has the following members, all integer: order_product_id (required), quantity (required), product_id (read-only). A sample items value might be: [ {"order_product_id":16,"product_id": 0,"quantity":2} ]

  • shipping_provider_display_name
    string

    The human-readable name for the shipping_provider.

  • generated_tracking_link
    string

    The tracking link that is generated using the combination of either the tracking_number and shipping_provider or tracking_number and tracking_carrier. This will be empty if the custom tracking_link value is provided.

application/json

Update a Shipment

PUT /orders/{order_id}/shipments/{shipment_id}

Request

Updates an existing shipment associated with an order.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Content-Type in header with default of application/json - string - required

    The MIME type of the request body.

Body

object | application/json
  • order_address_id
    integer

    ID of the desired shipping_address associated with the shipment.

    Example: 20

  • tracking_number
    string

    Tracking number of the shipment.

    Example: w4se4b6ASFEW4T

  • shipping_method
    string

    Additional information to describe the method of shipment (ex. Standard, Ship by Weight, Custom Shipment). Can be used for live quotes from certain shipping providers. If different from shipping_provider, shipping_method should correspond to tracking_carrier.

    Example: Ship by Weight

  • shipping_provider

    Any of:

    Example: shipperhq

  • tracking_carrier
    string

    Tracking carrier for the shipment. Acceptable values for tracking_carrier include an empty string ("") or one of the valid tracking-carrier values.

    Example:

  • tracking_link
    string

    The custom tracking link supplied on POST or PUT shipments. For the auto-generated tracking link see the generated_tracking_link property.

    <= 500 characters

    Example: https://www.mycustomtrackinglink.com/tracking

  • comments
    string

    Comments the shipper wishes to add.

    <= 65535 characters

application/json

Response

Body

object | application/json
  • id
    integer

    Shipment ID.

    Example: 1

  • order_id
    integer

    ID of the order associated with this shipment.

    Example: 120

  • customer_id
    integer

    ID of this order’s customer.

    Example: 5

  • order_address_id
    integer

    ID of the desired shipping_address associated with the shipment.

    Example: 20

  • date_created
    string

    Creation date for the shipment.

  • tracking_number
    string

    Tracking number of the shipment.

    Example: w4se4b6ASFEW4T

  • shipping_method
    string

    Additional information to describe the method of shipment (ex. Standard, Ship by Weight, Custom Shipment). Can be used for live quotes from certain shipping providers. If different from shipping_provider, shipping_method should correspond to tracking_carrier.

    Example: Ship by Weight

  • shipping_provider

    Any of:

    Example: shipperhq

  • tracking_carrier
    string

    Tracking carrier for the shipment. Acceptable values for tracking_carrier include an empty string ("") or one of the valid tracking-carrier values.

    Example:

  • tracking_link
    string

    The custom tracking link supplied on POST or PUT shipments. For the auto-generated tracking link see the generated_tracking_link property.

  • comments
    string

    Comments the shipper wishes to add.

    <= 65535 characters
  • billing_address
    object

  • shipping_address
    object

    Shipping Address properties common to all requests and responses.

  • items
    array[object]

    The items in the shipment. This object has the following members, all integer: order_product_id (required), quantity (required), product_id (read-only). A sample items value might be: [ {"order_product_id":16,"product_id": 0,"quantity":2} ]

  • shipping_provider_display_name
    string

    The human-readable name for the shipping_provider.

  • generated_tracking_link
    string

    The tracking link that is generated using the combination of either the tracking_number and shipping_provider or tracking_number and tracking_carrier. This will be empty if the custom tracking_link value is provided.

application/json

Delete an Order Shipment

DELETE /orders/{order_id}/shipments/{shipment_id}

Request

Deletes a shipment associated with an order.

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string - required

    The MIME type of the response body.

  • order_id in path - integer - required

    ID of the order.

  • shipment_id in path - integer - required

    Shipment ID.

example

Response

Did you find what you were looking for?