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.
DocumentationAPI Reference
DocumentationAPI Reference
  • API Reference
      • GETGet Order
      • GETGet Shipment Logs
      • POSTMark Tracking Uploaded
      • GETGet All Shipments for Order
      • GETGet Order Store Data
      • POSTEstimate Fulfillment Cost For Order
      • GETGet Orders
      • POSTCreate Order
      • POSTCancel Shipment
      • POSTCancel Shipment by Order ID and Shipment ID
      • GETGet Shipping Methods
      • POSTCancel Order
      • GETGet Shipment Logs by Order ID and Shipment ID
      • GETGet Shipment Status Timeline by Order ID and Shipment ID
      • GETGet Shipment Timeline
      • GETGet Shipment
      • POSTBatch Cancel Shipments
      • GETGet Shipment by Order ID and Shipment ID
      • PUTBulk Update Shipping Service
      • POSTUpdate Shipment Line Items
      • PUTUpdate Shipment Address
      • GETGet Shipment Line Items
      • GETGet Completely Cancelled Orders
LogoLogo
API ReferenceOrders

Create Order

||View as Markdown|
POST
https://sandbox-api.shipbob.com/2026-01/order
POST
/2026-01/order
$curl -X POST https://sandbox-api.shipbob.com/2026-01/order \
>     -H "shipbob_channel_id: 1" \
>     -H "Authorization: Bearer <token>" \
>     -H "Content-Type: application/json-patch+json" \
>     -d '{
>  "products": [
>    {
>      "external_line_id": 0,
>      "name": "TShirtBlueM",
>      "quantity": 1,
>      "quantity_unit_of_measure_code": "string",
>      "reference_id": "TShirtBlueM"
>    }
>  ],
>  "recipient": {
>    "address": null,
>    "name": "John Doe",
>    "email": "john@example.com",
>    "phone_number": "555-555-5555"
>  },
>  "reference_id": "string",
>  "shipping_method": "Free 2-day Shipping",
>  "type": "DTC",
>  "financials": {
>    "total_price": 0.1
>  },
>  "gift_message": "string",
>  "location_id": 0,
>  "order_number": "string",
>  "purchase_date": "2019-08-24T14:15:22+00:00",
>  "retailer_program_data": {
>    "addresses": [
>      {
>        "address1": "100 Nowhere Blvd",
>        "city": "Gotham City",
>        "country": "US",
>        "type": "MarkFor",
>        "address2": "Suite 100",
>        "company_name": "Wayne Enterprises",
>        "state": "NJ",
>        "zip_code": "07093"
>      }
>    ],
>    "customer_ticket_number": "string",
>    "delivery_date": "2019-08-24T14:15:22+00:00",
>    "department": "string",
>    "doNotShipBeforeDate": "2019-08-24T14:15:22+00:00",
>    "mark_for_store": "string",
>    "purchase_order_number": "string",
>    "retailer_program_type": "string",
>    "shipByDate": "2019-08-24T14:15:22+00:00"
>  },
>  "shipping_terms": {
>    "carrier_type": "Parcel",
>    "payment_term": "Collect"
>  },
>  "tags": [
>    {
>      "name": "Handling instructions",
>      "value": "Fragile"
>    }
>  ]
>}'
1{
2  "channel": {
3    "id": 0,
4    "name": "ShipBobs-Shopify-Store"
5  },
6  "created_date": "2019-08-24T14:15:22+00:00",
7  "financials": {
8    "total_price": 0.1
9  },
10  "gift_message": "string",
11  "id": 0,
12  "order_number": "string",
13  "products": [
14    {
15      "external_line_id": 0,
16      "gtin": "string",
17      "id": 0,
18      "quantity": 0,
19      "quantity_unit_of_measure_code": "string",
20      "reference_id": "TShirtBlueM",
21      "sku": "TShirtBlueM",
22      "unit_price": 0.1,
23      "upc": "string"
24    }
25  ],
26  "purchase_date": "2019-08-24T14:15:22+00:00",
27  "recipient": {
28    "address": null,
29    "name": "John Doe",
30    "email": "john@example.com",
31    "phone_number": "555-555-5555"
32  },
33  "reference_id": "string",
34  "retailer_program_data": {
35    "addresses": [
36      {
37        "address1": "100 Nowhere Blvd",
38        "city": "Gotham City",
39        "country": "US",
40        "type": "MarkFor",
41        "address2": "Suite 100",
42        "company_name": "Wayne Enterprises",
43        "state": "NJ",
44        "zip_code": "07093"
45      }
46    ],
47    "customer_ticket_number": "string",
48    "delivery_date": "2019-08-24T14:15:22+00:00",
49    "department": "string",
50    "doNotShipBeforeDate": "2019-08-24T14:15:22+00:00",
51    "mark_for_store": "string",
52    "purchase_order_number": "string",
53    "retailer_program_type": "string",
54    "shipByDate": "2019-08-24T14:15:22+00:00"
55  },
56  "shipments": [
57    {
58      "actual_fulfillment_date": "2019-08-24T14:15:22+00:00",
59      "created_date": "2019-08-24T14:15:22+00:00",
60      "delivery_date": "2019-08-24T14:15:22+00:00",
61      "estimated_fulfillment_date": "2019-08-24T14:15:22+00:00",
62      "estimated_fulfillment_date_status": "AwaitingInventoryAllocation",
63      "gift_message": "string",
64      "id": 0,
65      "insurance_value": 0,
66      "invoice_amount": 0,
67      "invoice_currency_code": "string",
68      "is_tracking_uploaded": true,
69      "last_tracking_update_at": "2019-08-24T14:15:22+00:00",
70      "last_update_at": "2019-08-24T14:15:22+00:00",
71      "location": {
72        "id": 0,
73        "name": "Cicero (IL)"
74      },
75      "measurements": {
76        "depth_in": 0,
77        "length_in": 0,
78        "total_weight_oz": 0,
79        "width_in": 0
80      },
81      "order_id": 0,
82      "package_material_type": "Unknown",
83      "parent_cartons": [
84        {
85          "barcode": "string",
86          "cartons": [
87            {
88              "barcode": "string",
89              "carton_details": [
90                {
91                  "products": [
92                    {
93                      "id": 0,
94                      "inventory_items": [
95                        {
96                          "expiration_date": "2019-08-24T14:15:22+00:00",
97                          "id": 0,
98                          "is_dangerous_goods": true,
99                          "lot": "22222",
100                          "name": "Medium Blue T-Shirt",
101                          "quantity": 0,
102                          "quantity_committed": 0,
103                          "serial_numbers": [
104                            "string"
105                          ]
106                        }
107                      ],
108                      "name": "Medium Blue T-Shirt",
109                      "reference_id": "TShirtBlueM",
110                      "sku": "TShirtBlueM"
111                    }
112                  ]
113                }
114              ],
115              "id": 0,
116              "measurements": {
117                "depth_in": 0.1,
118                "length_in": 0.1,
119                "total_weight_oz": 0.1,
120                "width_in": 0.1
121              },
122              "type": "Box or pallet"
123            }
124          ],
125          "measurements": {
126            "depth_in": 0.1,
127            "length_in": 0.1,
128            "total_weight_oz": 0.1,
129            "width_in": 0.1
130          },
131          "type": "Box or pallet"
132        }
133      ],
134      "products": [
135        {
136          "id": 0,
137          "inventory_items": [
138            {
139              "expiration_date": "2019-08-24T14:15:22+00:00",
140              "id": 0,
141              "is_dangerous_goods": true,
142              "lot": "22222",
143              "name": "Medium Blue T-Shirt",
144              "quantity": 0,
145              "quantity_committed": 0,
146              "serial_numbers": [
147                "string"
148              ]
149            }
150          ],
151          "name": "Medium Blue T-Shirt",
152          "reference_id": "TShirtBlueM",
153          "sku": "TShirtBlueM"
154        }
155      ],
156      "recipient": {
157        "address": null,
158        "email": "john@example.com",
159        "full_name": "John Doe",
160        "name": "John Doe",
161        "phone_number": "555-555-5555"
162      },
163      "reference_id": "string",
164      "require_signature": true,
165      "ship_option": "Standard",
166      "status": "None",
167      "status_details": [
168        {
169          "description": "string",
170          "exception_fulfillment_center_id": 0,
171          "extra_information": {
172            "validation_messages": [
173              "string"
174            ]
175          },
176          "id": 0,
177          "inventory_id": 0,
178          "name": "string"
179        }
180      ],
181      "tracking": {
182        "bol": "string",
183        "carrier": "USPS",
184        "carrier_service": "Priority",
185        "pro_number": "string",
186        "scac": "string",
187        "shipping_date": "2019-08-24T14:15:22+00:00",
188        "tracking_number": "860C8CDC8F0B4FC7AB69AC86C20539EC",
189        "tracking_url": "https://www.example.com/tracking?id=860C8CDC8F0B4FC7AB69AC86C20539EC"
190      }
191    }
192  ],
193  "shipping_method": "Free 2-day Shipping",
194  "shipping_terms": {
195    "carrier_type": "Parcel",
196    "payment_term": "Collect"
197  },
198  "status": "Processing",
199  "tags": [
200    {
201      "name": "Handling instructions",
202      "value": "Fragile"
203    }
204  ],
205  "type": "DTC"
206}

Creates a new order in ShipBob’s system that will be queued for fulfillment. Orders can be created using either product reference IDs (SKUs) or ShipBob product IDs, with reference IDs being the recommended approach.

Was this page helpful?
Previous

Get Orders

Next

Cancel Shipment

Built with

Authentication

AuthorizationBearer

Authentication using Personal Access Token (PAT) token

OR
AuthorizationBearer
OAuth2 authentication using JWT tokens

Headers

shipbob_channel_idintegerRequired
Channel Id for Operation

Request

productslist of objectsRequired

Products included in the order. Products identified by reference_id must also include the product name if there is no matching ShipBob product.

recipientobjectRequired
Information about the recipient of an order
reference_idstringRequired1-300 characters
Unique and immutable order identifier from your upstream system
shipping_methodstringRequired>=1 character

Client-defined shipping method matching what the user has listed as the shipping method on the Ship Option Mapping setup page in the ShipBob Merchant Portal. If they don’t match, we will create a new one and default it to Standard

typeenumRequired
Allowed values:
financialsobjectOptional
gift_messagestringOptional<=500 characters
Gift message associated with the order
location_idintegerOptional
Desired Fulfillment Center Location ID. If not specified, ShipBob will determine the location that fulfills this order.
order_numberstringOptional<=400 characters
User friendly orderId or store order number that will be shown on the Orders Page. If not provided, referenceId will be used
origin_platform_programstringOptional<=100 characters
Origin platform program for the order. Accepts a program name.
purchase_datedatetimeOptional
Date this order was purchase by the end user
requested_delivery_datedatetimeOptional
The delivery date requested by the source platform for the order in UTC
retailer_program_dataobjectOptional

Contains properties that needs to be used for fulfilling B2B/Dropship orders.

sales_channelenumOptional
shipping_termsobjectOptional
Contains shipping properties that need to be used for fulfilling an order.
tagslist of objectsOptional
Key value pair array to store extra information at the order level for API purposes. ShipBob won't display the info in the ShipBob Merchant Portal or react based on this data.

Response

Created
channelobject
Created by channel metadata
created_datedatetime
Date this order was created
financialsobject
gift_messagestring
Gift message associated with the order
idinteger
Unique id of the order
order_numberstring
User friendly orderId or store order number that will be shown on the Orders Page. If not provided, referenceId will be used
productslist of objects
List of products included in the order
purchase_datedatetime
Date this order was purchase by the end user
recipientobject
Information about the recipient of an order
reference_idstring

Client-defined external unique id of the order

retailer_program_dataobject

Contains properties that needs to be used for fulfilling B2B/Dropship orders.

shipmentslist of objects
Shipments affiliated with the order
shipping_methodstring

Client-defined shipping method

shipping_termsobject
Contains shipping properties that need to be used for fulfilling an order.
statusenum
tagslist of objects

Client-defined order tags

typeenum
Allowed values:

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
422
Unprocessable Entity Error