Integration GuidesOrders

Build an Orders Integration

View as Markdown

Overview

The ShipBob Orders API enables you to programmatically create orders, retrieve tracking information, and manage fulfillment. This guide walks you through building a complete orders integration.

Before you begin, ensure:

  • Your API key has the orders_write and orders_read access scopes
  • You have your ShipBob channel ID (get it here)

How It Works

Here’s the complete order lifecycle from creation to delivery tracking:

Step 1: Create an Order

Use the Create Order endpoint to create an order.

Make sure to pass the shipbob_channel_id in the request header. This identifies which channel the order belongs to.
POST https://{env}.shipbob.com/{api_version}/order lines
1{
2  "shipping_method": "Standard",
3  "recipient": {
4    "name": "John Doe",
5    "address": {
6      "address1": "100 N Racine Ave",
7      "address2": "Suite 100",
8      "company_name": null,
9      "city": "Chicago",
10      "state": "IL",
11      "country": "US",
12      "zip_code": "60607"
13    },
14    "email": "johndoe@domain.com",
15    "phone_number": "555-555-5555"
16  },
17  "products": [
18    {
19      "name": "Light Roast Coffee",
20      "reference_id": "LIGHT-ROAST",
21      "quantity": 1
22    }
23  ],
24  "reference_id": "1234762738908",
25  "order_number": "1001",
26  "type": "DTC",
27  "tags": [
28    {
29      "name": "Subscription Order",
30      "value": "0"
31    },
32    {
33      "name": "New Customer",
34      "value": "0"
35    }
36  ]
37}

What you’ll get back:

The response returns information about the order and associated shipments, including the shipment IDs, line items, and the assigned fulfillment center.

JSON response lines
1{
2  "id": 309589638,
3  "created_date": "2025-11-19T00:06:43.7807166+00:00",
4  "purchase_date": null,
5  "reference_id": "1234762738908",
6  "order_number": "1001",
7  "status": "ImportReview",
8  "type": "DTC",
9  "channel": {
10    "id": 432951,
11    "name": "PAT Channel"
12  },
13  "shipping_method": "Standard",
14  "recipient": {
15    "name": "John Doe",
16    "address": {
17      "address1": "100 N Racine Ave",
18      "address2": "Suite 100",
19      "city": "Chicago",
20      "state": "IL",
21      "country": "US",
22      "zip_code": "60607"
23    },
24    "email": "johndoe@domain.com",
25    "phone_number": "555-555-5555"
26  },
27  "products": [
28    {
29      "id": 1377083100,
30      "reference_id": "LIGHT-ROAST",
31      "quantity": 1,
32      "quantity_unit_of_measure_code": "EA",
33      "sku": "LIGHT-ROAST",
34      "gtin": "",
35      "upc": "",
36      "unit_price": null,
37      "external_line_id": null
38    }
39  ],
40  "tags": [
41    {
42      "name": "Subscription Order",
43      "value": "0"
44    },
45    {
46      "name": "New Customer",
47      "value": "0"
48    }
49  ],
50  "shipments": [
51    {
52      "id": 317255024,
53      "order_id": 309589638,
54      "reference_id": "1234762738908",
55      "recipient": {
56        "name": "John Doe",
57        "full_name": "John Doe",
58        "address": {
59          "address1": "100 N Racine Ave",
60          "address2": "Suite 100",
61          "company_name": null,
62          "city": "Chicago",
63          "state": "IL",
64          "country": "US",
65          "zip_code": "60607"
66        },
67        "email": "johndoe@domain.com",
68        "phone_number": "555-555-5555"
69      },
70      "created_date": "2025-11-19T00:06:43.7807166+00:00",
71      "last_update_at": null,
72      "last_tracking_update_at": null,
73      "status": "ImportReview",
74      "status_details": [],
75      "location": null,
76      "invoice_amount": 0.0,
77      "invoice_currency_code": null,
78      "insurance_value": null,
79      "ship_option": "Ground",
80      "tracking": null,
81      "products": [
82        {
83          "id": 1377083100,
84          "reference_id": "LIGHT-ROAST",
85          "name": "Light Roast Coffee",
86          "sku": "LIGHT-ROAST",
87          "inventory_items": [
88            {
89              "id": 21756231,
90              "name": "Light Roast Coffee",
91              "quantity": 1
92            }
93          ]
94        }
95      ]
96      // ... additional shipment fields omitted for brevity
97    }
98  ]
99  // ... additional fields omitted for brevity
100}

The reference_id field is your idempotency key. If ShipBob receives two identical requests with the same reference_id + shipbob_channel_id, it will return a 422 error.

Step 2: Retrieve Tracking Details

ShipBob offers two workflows for retrieving shipment details:

Webhooks

Real time updates via webhooks. Click to jump to this section.

Polling

Poll the API on a schedule. Click to jump to this section.

Webhooks

ShipBob can fire webhooks for shipment events including:

  • Shipped (order.shipped) - When a shipment leaves the warehouse. This is the primary webhook for syncing tracking details.
  • Delivered - When the carrier confirms delivery
  • Exception - Product out of stock or other fulfillment issues
  • On Hold - Invalid address or payment issues
  • Cancelled - Shipment was cancelled

How to subscribe:

  1. Via Dashboard: Go to Integrations > Webhooks > Add Subscription Create webhook subscription
  2. Via API: Use the Create Webhook Subscription endpoint

Learn more in the Webhooks documentation.

ShipBob uses exponential backoff to retry webhook delivery for up to 24 hours, but cannot guarantee events arrive in the original sequence. Always check timestamps when processing webhooks.

Polling

Poll the GET Orders endpoint on a recurring schedule (every 15-30 minutes).

Key parameters:

  • HasTracking - Filter for orders where tracking is available (shipment has been labeled)
  • IsTrackingUploaded - Use as a sync flag. Set to false to find unsynced orders

Recommended Request

Get all orders that have been shipped but not uploaded to your system. Look at the total-count or total-pages parameter in the header of the response to determine if you need to use pagination.

GET https://{env}.shipbob.com/{api_version}/order?HasTracking=true&IsTrackingUploaded=false&Limit=250&Page=1

Workflow:

Pass the shipbob_channel_id header to only retrieve orders from your integration channel, avoiding data from other integrations the merchant may have installed.

Understanding split shipments:

An order can have multiple shipments if:

  • Inventory is stocked in multiple fulfillment centers
  • Items don’t fit in one box due to size/weight

When a shipment has tracking, its status will be LabeledCreated, which quickly transitions to Completed. Always loop through the shipments[] array in the order response.

Example: Order with split shipments

1{
2  "id": 123456,
3  "reference_id": "ORDER-001",
4  "status": "Partially Fulfilled",
5  "shipments": [
6    {
7      "id": 789101,
8      "status": "Completed",
9      "tracking": {
10        "number": "1Z999AA10123456784",
11        "carrier": "UPS"
12      },
13      "products": [
14        { "reference_id": "SKU-A", "quantity": 1 }
15      ]
16    },
17    {
18      "id": 789102,
19      "status": "Processing",
20      "tracking": null,
21      "products": [
22        { "reference_id": "SKU-B", "quantity": 2 }
23      ]
24    }
25  ]
26}

For complete order and shipment status details, see the Status Reference.

Step 3: Mark Tracking as Synced

After syncing tracking to your system, mark shipments as uploaded to prevent re-processing:

POST https://{env}.shipbob.com/{api_version}/shipment:batchUpdateTrackingUpload
{
  "shipment_ids": [789101, 789102],
  "is_tracking_uploaded": true
}

This updates the IsTrackingUploaded flag so future queries with IsTrackingUploaded=false won’t return these shipments.

Retrieve Orders and Shipments

Get a specific order:

GET https://{env}.shipbob.com/{api_version}/order/{id}

Get a specific shipment:

GET https://{env}.shipbob.com/{api_version}/shipment/{id}
When looking at the order response payload, the shipment id is in the shipments array.

Search for Orders

Use query parameters on the GET Orders endpoint to search for orders.

Common search queries:

Use CaseQuery Example
Orders with tracking informationorder?HasTracking=true&IsTrackingUploaded=false
Search by reference IDorder?ReferenceIds=1234762738908
Orders within a date rangeorder?StartDate=2025-11-01&EndDate=2025-11-30

Get orders with tracking that haven’t been synced:

GET https://{env}.shipbob.com/{api_version}/order?HasTracking=true&IsTrackingUploaded=false&Limit=250

Example: Search by reference_id:

GET https://{env}.shipbob.com/{api_version}/order?ReferenceIds=1234762738908

Example: Get all orders for November 2025:

GET https://{env}.shipbob.com/{api_version}/order?StartDate=2025-11-01&EndDate=2025-11-30

Cancel an Order

You can cancel orders and shipments that haven’t been picked, packed or shipped yet using the Cancel Order endpoint.

Once a shipment is Picked, it cannot be cancelled. The order has already been physically picked from the warehouse shelves.

Cancel an Entire Order

1POST https://{env}.shipbob.com/{api_version}/order/{orderId}/cancel

Example request:

$curl -X POST \
>  https://api.shipbob.com/2026-01/order/309589638/cancel \
>  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
>  -H 'shipbob_channel_id: 432951'

Cancel Individual Shipments

If an order has multiple shipments and you only want to cancel specific ones:

1POST https://{env}.shipbob.com/{api_version}/shipment/{shipmentId}/cancel

Example request:

$curl -X POST \
>  https://api.shipbob.com/2026-01/shipment/317255024/cancel \
>  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
>  -H 'shipbob_channel_id: 432951'

Important Fields

reference_id - Your unique order identifier. Acts as an idempotency key - duplicate reference_id + shipbob_channel_id combinations return a 422 error.

order_number - User-friendly order number for customer service. Does not need to be unique (can match reference_id).

shipping_method - Value like “Standard”, “Expedited”, or “2-Day”. Merchants map this to ShipBob Ship Options that determine SLA and carrier selection. See Ship Options guide.

type - Order type:

  • DTC - Direct-to-consumer orders (most common)
  • B2B - Business-to-business orders (see B2B Orders guide)

shipbob_channel_id (header) - Identifies which channel the order belongs to. Get your channel ID from the GET Channels endpoint.

products.reference_id - SKU or unique product identifier. Must match a product created in ShipBob (see Product Management Guide).

IsTrackingUploaded - Boolean flag indicating if you’ve synced the tracking to your system. Use this to prevent duplicate processing.

Common Issues

Each order must have a unique reference_id within a channel. If you need to resubmit, use a different reference_id or cancel the original order first.

Ensure required fields are provided: address1, city, country (ISO Alpha-2 code), and ideally state and zip_code.

Call the GET Channels endpoint. Look for the channel with _write scopes — that’s your integration channel.

Check the status_details field in the shipment for specific reasons. Common causes: out of stock, invalid address, missing customs info. See Status Reference for details.

Tips

  • Poll every 15-30 minutes - Don’t check more frequently than every 5 minutes to avoid rate limits
  • API rate limit - 150 requests per minute
  • Always use shipbob_channel_id header - Prevents retrieving orders from other integrations
  • Use webhooks + polling fallback - Webhooks for real-time updates, polling as a safety net
  • Handle split shipments - Always loop through order.shipments[] and sync each tracking number separately
  • Mark tracking as uploaded - Use the batchUpdateTrackingUpload endpoint to avoid re-processing
  • If your integration receives unexpected edit or update requests to orders after creation, consider implementing a 1-hour delay before sending orders to ShipBob