Docs
Management API
Orders
Order Shipments

Order Shipments

Get Order Shipments

GET /orders/{order_id}/shipments

Request

Gets a list of all shipments on an order.

Authentication

  • X-Auth-Token in header

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.
  • page in query with default of 1 - number
    The page to return in the response.
  • limit in query with default of 50 - 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

  • merchant_shipping_cost    string

    Shipping cost for the merchant.
    Example: 1.0000

  • 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:

    Allowed: auspost | canadapost | endicia | usps | fedex | ups | upsready | upsonline | shipperhq | royalmail |

    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.

  • tracking_link    string

    The custom tracking link supplied on POST or PUT shipments. For the link to one of our integrated providers or Aftership 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
    read-only

    The human-readable name for the shipping_provider.

  • generated_tracking_link    string

    The link to one of our integrated providers or Aftership 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 a link to one of our integrated providers that you can click from the BigCommerce control panel and customer-facing emails. If a merchant still needs to set up a shipping provider or if the provider is not one of our natively integrated providers, you will click on an Aftership tracking link instead. The generated_tracking_link property in the API response represents one of these tracking links. The tracking_link property in the API response will remain empty.

  2. Use tracking_carrier and tracking_number: This also creates a link to one of our integrated providers or an Aftership 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
  • 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

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.
  • 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 link to one of our integrated providers or Aftership tracking link see the generated_tracking_link property.
    <= 500 characters
    Example: https://www.mycustomtrackinglink.com/tracking

  • merchant_shipping_cost    string

    Shipping cost for the merchant.
    Example: 1.0000

  • 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:

    Allowed: auspost | canadapost | endicia | usps | fedex | ups | upsready | upsonline | shipperhq | royalmail |

    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.

  • 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

  • merchant_shipping_cost    string

    Shipping cost for the merchant.
    Example: 1.0000

  • 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:

    Allowed: auspost | canadapost | endicia | usps | fedex | ups | upsready | upsonline | shipperhq | royalmail |

    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.

  • tracking_link    string

    The custom tracking link supplied on POST or PUT shipments. For the link to one of our integrated providers or Aftership 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
    read-only

    The human-readable name for the shipping_provider.

  • generated_tracking_link    string

    The link to one of our integrated providers or Aftership 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

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

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

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

  • merchant_shipping_cost    string

    Shipping cost for the merchant.
    Example: 1.0000

  • 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:

    Allowed: auspost | canadapost | endicia | usps | fedex | ups | upsready | upsonline | shipperhq | royalmail |

    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.

  • tracking_link    string

    The custom tracking link supplied on POST or PUT shipments. For the link to one of our integrated providers or Aftership 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
    read-only

    The human-readable name for the shipping_provider.

  • generated_tracking_link    string

    The link to one of our integrated providers or Aftership 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

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.
  • 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

  • merchant_shipping_cost    string

    Shipping cost for the merchant.
    Example: 1.0000

  • 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:

    Allowed: auspost | canadapost | endicia | usps | fedex | ups | upsready | upsonline | shipperhq | royalmail |

    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.

  • tracking_link    string

    The custom tracking link supplied on POST or PUT shipments. For the link to one of our integrated providers or Aftership 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

  • merchant_shipping_cost    string

    Shipping cost for the merchant.
    Example: 1.0000

  • 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:

    Allowed: auspost | canadapost | endicia | usps | fedex | ups | upsready | upsonline | shipperhq | royalmail |

    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.

  • tracking_link    string

    The custom tracking link supplied on POST or PUT shipments. For the link to one of our integrated providers or Aftership 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
    read-only

    The human-readable name for the shipping_provider.

  • generated_tracking_link    string

    The link to one of our integrated providers or Aftership 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

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?
Get an Order ProductGet Order Shipments