For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dev Portal
DocsAPI ReferenceLearnCommunityChangelog
DocsAPI ReferenceLearnCommunityChangelog
    • About Our APIs
  • REST
    • Overview
      • Overview
        • Abandoned Carts
        • Carts
        • Channels
        • Checkouts
        • Currencies
        • Customer Segmentation
        • Geography
        • Infrastructure Hosting
        • Inventory
        • Orders
            • GETGet Order
            • PUTUpdate Order
            • DELArchive Order
            • GETGet Count of Orders
            • GETList Orders
            • POSTCreate Order
            • DELDelete All Orders
              • GETList Order Shipments
              • POSTCreate Order Shipment
              • DELDelete Order Shipments
              • GETGet Count of Order Shipments
              • GETGet Shipment
              • PUTUpdate Shipment
              • DELDelete Order Shipment
        • Order Operations
        • Pickup
        • Pickup Methods
        • Pickup Options
        • Pricing
        • Price Lists
        • Promotions
        • Promotion Settings
        • Redirects
        • Scripts
        • Settings
        • Shipping
        • Sites
        • Subscribers
        • System Logs
        • Tax
        • Wishlists
      • Payments
  • GraphQL
    • Overview
  • MCP
    • Overview
Dev Portal
LogoLogo
RESTAdminManagementOrdersOrder Shipments

Create Order Shipment

POST
https://api.bigcommerce.com/stores/:store_hash/v2/orders/:order_id/shipments
POST
/stores/:store_hash/v2/orders/:order_id/shipments
$curl -X POST https://api.bigcommerce.com/stores/store_hash/v2/orders/1/shipments \
>     -H "Accept: application/json" \
>     -H "X-Auth-Token: <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{}'
201application/json
1{
2  "id": 11,
3  "order_id": 228,
4  "customer_id": 11,
5  "order_address_id": 131,
6  "date_created": "Wed, 13 Mar 2019 16:35:37 +0000",
7  "tracking_number": "EJ958083578US",
8  "merchant_shipping_cost": "0.0000",
9  "shipping_method": "None",
10  "shipping_provider": "usps",
11  "tracking_carrier": "",
12  "tracking_link": "",
13  "comments": "Ready to go...",
14  "billing_address": {
15    "zip": "78751",
16    "first_name": "Jane",
17    "last_name": "Doe",
18    "company": "",
19    "street_1": "123 Main Street",
20    "street_2": "",
21    "city": "Austin",
22    "state": "Texas",
23    "country": "United States",
24    "country_iso2": "US",
25    "phone": "",
26    "email": "janedoe@example.com"
27  },
28  "shipping_address": {
29    "first_name": "Trishy",
30    "last_name": "Test",
31    "company": "Acme Pty Ltd",
32    "street_1": "666 Sussex St",
33    "street_2": "",
34    "city": "Anywhere",
35    "state": "Some State",
36    "zip": "12345",
37    "country": "United States",
38    "country_iso2": "US",
39    "phone": "",
40    "email": "elsie@example.com"
41  },
42  "items": [
43    {
44      "order_product_id": 194,
45      "product_id": 0,
46      "quantity": 1
47    },
48    {
49      "order_product_id": 195,
50      "product_id": 0,
51      "quantity": 1
52    }
53  ],
54  "shipping_provider_display_name": "USPS",
55  "generated_tracking_link": "http://trkcnfrm1.smi.usps.com/PTSInternetWeb/InterLabelInquiry.do?strOrigTrackNum=EJ958083578US"
56}
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).
Was this page helpful?
Previous

List Order Shipments

Next

Delete Order Shipments

Built with

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 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-fundamentals/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-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/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_idintegerRequired
ID of the order.
store_hashstringRequired
Permanent ID of the BigCommerce store.

Headers

AcceptstringRequiredDefaults to application/json
The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) 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.
tracking_linkstringOptional<=500 characters

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.

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

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.

tracking_linkstring

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.

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.

generated_tracking_linkstring

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.

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.

The MIME type of the response body.