Create Order Shipment

Creates an *Order Shipment*. For more details, see [Shipping an Order](/developer/docs/admin/checkout-and-cart/orders#creating-order-shipments). **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](/developer/docs/integrations/shipping-providers) Acceptable values for `tracking_carrier` include an empty string (`""`) or one of the valid [tracking-carrier values](https://www.aftership.com/docs/tracking/others/supported-couriers).

Authentication

X-Auth-Tokenstring
### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Orders | modify | `store_v2_orders` | | Orders | read-only | `store_v2_orders_read_only` | ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

Path parameters

order_idstringRequired

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](https://www.aftership.com/docs/tracking/others/supported-couriers).
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

idinteger
Shipment ID.
order_idinteger
ID of the order associated with this shipment.
customer_idinteger

ID of this order’s customer.

order_address_idinteger

ID of the desired shipping_address associated with the shipment.

date_createdstring
Creation date for the shipment.
tracking_numberstring
Tracking number of the shipment.
merchant_shipping_coststring
Shipping cost for the merchant.
shipping_methodstring

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 string
tracking_carrierstring
Tracking carrier for the shipment. Acceptable values for `tracking_carrier` include an empty string (`""`) or one of the valid [tracking-carrier values](https://www.aftership.com/docs/tracking/others/supported-couriers).
commentsstring<=65535 characters
Comments the shipper wishes to add.
billing_addressobject
shipping_addressobject
Shipping Address properties common to all requests and responses.
itemslist of objects

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

The human-readable name for the shipping_provider.