Thanks for being patient while we implement your feedback to improve the developer experience.

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

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/orders/[order_id]/shipments' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

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    string

    Enum of the BigCommerce shipping-carrier integration/module.

    Allowed: auspost | canadapost | endicia | usps | fedex | ups | upsready | upsonline | 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

    Returns a tracking link from the shipping service.

  • 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} ]

application/json

[
  {
    "id": 6,
    "order_id": 225,
    "customer_id": 11,
    "order_address_id": 127,
    "date_created": "Mon, 11 Mar 2019 17:22:08 +0000",
    "tracking_number": "EJ958083578US",
    "merchant_shipping_cost": "0.0000",
    "shipping_method": "None",
    "comments": "Ready to go...",
    "shipping_provider": "usps",
    "tracking_carrier": "",
    "tracking_link": "",
    "billing_address": {
      "first_name": "Jane",
      "last_name": "Does",
      "company": "",
      "street_1": "123 Main Street",
      "street_2": "",
      "city": "Austin",
      "state": "Texas",
      "zip": "78751",
      "country": "United States",
      "country_iso2": "US",
      "phone": "",
      "email": "janedoe@example.com"
    },
    "shipping_address": {
      "first_name": "Trishy",
      "last_name": "Test",
      "company": "Acme Pty Ltd",
      "street_1": "666 Sussex St",
      "street_2": "",
      "city": "Anywhere",
      "state": "Some State",
      "zip": "12345",
      "country": "United States",
      "country_iso2": "US",
      "phone": "",
      "email": "elsie@example.com"
    },
    "items": [
      {
        "order_product_id": 188,
        "product_id": 0,
        "quantity": 1
      }
    ]
  },
  {
    "id": 7,
    "order_id": 225,
    "customer_id": 11,
    "order_address_id": 128,
    "date_created": "Mon, 11 Mar 2019 17:22:31 +0000",
    "tracking_number": "EJ958083578UK",
    "merchant_shipping_cost": "0.0000",
    "shipping_method": "None",
    "comments": "Janes Order",
    "shipping_provider": "usps",
    "tracking_carrier": "",
    "tracking_link": "",
    "billing_address": {
      "first_name": "Jane",
      "last_name": "Does",
      "company": "",
      "street_1": "123 Main Street",
      "street_2": "",
      "city": "Austin",
      "state": "Texas",
      "zip": "78751",
      "country": "United States",
      "country_iso2": "US",
      "phone": "",
      "email": "janedoe@example.com"
    },
    "shipping_address": {
      "first_name": "Jane",
      "last_name": "Doe",
      "company": "",
      "street_1": "555 Main Street",
      "street_2": "",
      "city": "Austin",
      "state": "Texas",
      "zip": "78751",
      "country": "United States",
      "country_iso2": "US",
      "phone": "",
      "email": "janedoe@example.com"
    },
    "items": [
      {
        "order_product_id": 189,
        "product_id": 0,
        "quantity": 1
      }
    ]
  }
]

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

Presuming that a valid carrier code is used, a tracking link is generated if either shipping_provider or tracking_carrier is supplied alongside a tracking number. Providing only the tracking number will result in non-clickable text in the customer facing email.

Acceptable values for shipping_provider include an empty string (""), auspost, canadapost, endicia, usps, fedex, royalmail, ups, upsready, upsonline, or shipperhq.

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

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

    Enum of the BigCommerce shipping-carrier integration/module.

    Allowed: auspost | canadapost | endicia | usps | fedex | ups | upsready | upsonline | 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

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

    Enum of the BigCommerce shipping-carrier integration/module.

    Allowed: auspost | canadapost | endicia | usps | fedex | ups | upsready | upsonline | 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

    Returns a tracking link from the shipping service.

  • 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} ]

application/json

{
  "id": 11,
  "order_id": 228,
  "customer_id": 11,
  "order_address_id": 131,
  "date_created": "Wed, 13 Mar 2019 16:35:37 +0000",
  "tracking_number": "EJ958083578US",
  "merchant_shipping_cost": "0.0000",
  "shipping_method": "None",
  "comments": "Ready to go...",
  "shipping_provider": "usps",
  "tracking_carrier": "",
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "",
    "street_1": "123 Main Street",
    "street_2": "",
    "city": "Austin",
    "state": "Texas",
    "zip": "78751",
    "country": "United States",
    "country_iso2": "US",
    "phone": "",
    "email": "janedoe@example.com"
  },
  "shipping_address": {
    "first_name": "Trishy",
    "last_name": "Test",
    "company": "Acme Pty Ltd",
    "street_1": "666 Sussex St",
    "street_2": "",
    "city": "Anywhere",
    "state": "Some State",
    "zip": "12345",
    "country": "United States",
    "country_iso2": "US",
    "phone": "",
    "email": "elsie@example.com"
  },
  "items": [
    {
      "order_product_id": 194,
      "product_id": 0,
      "quantity": 1
    },
    {
      "order_product_id": 195,
      "product_id": 0,
      "quantity": 1
    }
  ]
}

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

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/orders/[order_id]/shipments' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

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

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/orders/[order_id]/shipments/count' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

  • count    number

    Example: 27

response

{
  "count": 27
}

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

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/orders/[order_id]/shipments/[shipment_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

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    string

    Enum of the BigCommerce shipping-carrier integration/module.

    Allowed: auspost | canadapost | endicia | usps | fedex | ups | upsready | upsonline | 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

    Returns a tracking link from the shipping service.

  • 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} ]

application/json

{
  "id": 11,
  "order_id": 228,
  "customer_id": 11,
  "order_address_id": 131,
  "date_created": "Wed, 13 Mar 2019 16:35:37 +0000",
  "tracking_number": "EJ958083578US",
  "merchant_shipping_cost": "0.0000",
  "shipping_method": "None",
  "comments": "Ready to go...",
  "shipping_provider": "usps",
  "tracking_carrier": "",
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "",
    "street_1": "123 Main Street",
    "street_2": "",
    "city": "Austin",
    "state": "Texas",
    "zip": "78751",
    "country": "United States",
    "country_iso2": "US",
    "phone": "",
    "email": "janedoe@example.com"
  },
  "shipping_address": {
    "first_name": "Trishy",
    "last_name": "Test",
    "company": "Acme Pty Ltd",
    "street_1": "666 Sussex St",
    "street_2": "",
    "city": "Anywhere",
    "state": "Some State",
    "zip": "12345",
    "country": "United States",
    "country_iso2": "US",
    "phone": "",
    "email": "elsie@example.com"
  },
  "items": [
    {
      "order_product_id": 194,
      "product_id": 0,
      "quantity": 1
    },
    {
      "order_product_id": 195,
      "product_id": 0,
      "quantity": 1
    }
  ]
}

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    string

    Enum of the BigCommerce shipping-carrier integration/module.

    Allowed: auspost | canadapost | endicia | usps | fedex | ups | upsready | upsonline | 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

application/json

{
  "tracking_number": "EJ958083578US",
  "order_address_id": 1,
  "shipping_provider": "",
  "items": [
    {
      "order_product_id": 15,
      "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    string

    Enum of the BigCommerce shipping-carrier integration/module.

    Allowed: auspost | canadapost | endicia | usps | fedex | ups | upsready | upsonline | 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

    Returns a tracking link from the shipping service.

  • 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} ]

application/json

{
  "id": 11,
  "order_id": 228,
  "customer_id": 11,
  "order_address_id": 131,
  "date_created": "Wed, 13 Mar 2019 16:35:37 +0000",
  "tracking_number": "EJ958083578US",
  "merchant_shipping_cost": "0.0000",
  "shipping_method": "None",
  "comments": "Ready to go...",
  "shipping_provider": "usps",
  "tracking_carrier": "",
  "billing_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "company": "",
    "street_1": "123 Main Street",
    "street_2": "",
    "city": "Austin",
    "state": "Texas",
    "zip": "78751",
    "country": "United States",
    "country_iso2": "US",
    "phone": "",
    "email": "janedoe@example.com"
  },
  "shipping_address": {
    "first_name": "Trishy",
    "last_name": "Test",
    "company": "Acme Pty Ltd",
    "street_1": "666 Sussex St",
    "street_2": "",
    "city": "Anywhere",
    "state": "Some State",
    "zip": "12345",
    "country": "United States",
    "country_iso2": "US",
    "phone": "",
    "email": "elsie@example.com"
  },
  "items": [
    {
      "order_product_id": 194,
      "product_id": 0,
      "quantity": 1
    },
    {
      "order_product_id": 195,
      "product_id": 0,
      "quantity": 1
    }
  ]
}

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

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/orders/[order_id]/shipments/[shipment_id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response