Build an Orders Integration

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.

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
      "unit_price": 14.99
23
    }
24
  ],
25
  "reference_id": "1234762738908",
26
  "order_number": "1001",
27
  "type": "DTC",
28
  "financials": {
29
    "total_price": 21.57
30
  },
31
  "tags": [
32
    {
33
      "name": "Subscription Order",
34
      "value": "0"
35
    },
36
    {
37
      "name": "New Customer",
38
      "value": "0"
39
    }
40
  ]
41
}

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.

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
}

Step 2: Retrieve Tracking Details

ShipBob offers two workflows for retrieving shipment details:

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
2. Via API: Use the Create Webhook Subscription endpoint

Learn more in the Webhooks documentation.

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

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

Workflow:

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}

Search for Orders

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

Common search queries:

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.

Cancel an Entire Order

1
POST 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:

1
POST 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

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

Related Resources

• Create Order API Reference
• Get Orders API Reference
• Webhooks Documentation
• Status Reference