Skip to navigation
RESTAdminManagementOrdersOrder Shipments

Create Order Shipment

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-Tokenstring

OAuth scopes

UI NamePermissionParameter
Ordersmodifystore_v2_orders
Ordersread-onlystore_v2_orders_read_only

Authentication header

HeaderArgumentDescription
X-Auth-Tokenaccess_tokenFor more about API accounts that generate access_tokens, see our Guide to API Accounts.

Further reading

For example requests and more information about authenticating BigCommerce APIs, see Authentication and Example Requests.

For more about BigCommerce OAuth scopes, see our Guide to API Accounts.

For a list of API status codes, see API Status Codes.

Path parameters

order_idintegerRequired
ID of the order.
store_hashstringRequired
Permanent ID of the BigCommerce store.

Headers

AcceptstringRequiredDefaults to application/json

The MIME type of the response body.

Request

This endpoint expects an object.
order_address_idintegerOptional

ID of the desired shipping_address associated with the shipment.

tracking_numberstringOptional<=50 characters
Tracking number of the shipment.
merchant_shipping_coststringOptional
Shipping cost for the merchant.
shipping_methodstringOptional

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.

shipping_providerenum or stringOptional
tracking_carrierstringOptional

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

commentsstringOptional<=65535 characters
Comments the shipper wishes to add.
itemslist of objectsOptional

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

The requested order shipment.
idintegerOptional
Shipment ID.
order_idintegerOptional
ID of the order associated with this shipment.
customer_idintegerOptional

ID of this order’s customer.

order_address_idintegerOptional

ID of the desired shipping_address associated with the shipment.

date_createdstringOptional
Creation date for the shipment.
tracking_numberstringOptional
Tracking number of the shipment.
merchant_shipping_coststringOptional
Shipping cost for the merchant.
shipping_methodstringOptional

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.

shipping_providerenum or stringOptional
tracking_carrierstringOptional

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

commentsstringOptional<=65535 characters
Comments the shipper wishes to add.
billing_addressobjectOptional
shipping_addressobjectOptional
Shipping Address properties common to all requests and responses.
itemslist of objectsOptional

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_namestringOptionalRead-only

The human-readable name for the shipping_provider.