***

title: ShipBob Logistics API
noindex: true
last-updated: 'February 24, 2026'
---------------------------------

This API lets you create shipping labels and sync tracking numbers for orders processed through ShipBob’s logistics system. It’s straightforward to integrate and works in both sandbox and production environments.

## Create an Account

To get started, you’ll need a ShipBob account. Sign up [here](https://web.shipbob.com/app/merchant/#/SignUp?utm_source=app_partner). After signing up, reach out to your ShipBob representative and they’ll guide you through the process and provide the necessary credentials.

## Base URLs

<Tabs>
  <Tab title="Production (Live)">
    ```javascript Base URL
    https://logisticslabelprintingapi.shipbob.com
    ```
  </Tab>

  <Tab title="Sandbox (Testing)">
    ```javascript Base URL
    https://logisticslabelprintingapi-stage.shipbob.dev
    ```
  </Tab>
</Tabs>

## Authentication

Authentication depends on the API you’re calling:

<Accordion title="For logisticslabelprintingapi Endpoints">
  For `https://logisticslabelprintingapi-stage.shipbob.dev/` or `https://logisticslabelprintingapi.shipbob.com/`:

  Use an `SBL_authToken` provided by your ShipBob rep:

  ```
  Authorization: <SBL_authToken>
  ```
</Accordion>

<Accordion title="For sandbox-api or api.shipbob.com Endpoints">
  For `https://sandbox-api.shipbob.com/` or `https://api.shipbob.com/`:

  Use a Personal Access Token (PAT), which you can generate in the ShipBob dashboard by going to **Integrations** > **API Tokens** > **Generate new token**.

  ```json
  Authorization: Bearer <Personal_Access_Token>
  ```
</Accordion>

## Create a Shipping Label

`POST /api/order:createLabel`

Generate a shipping label for an order. Labels default to ZPL format, but you can request PDF by adding a `Label-Type` header.

**Headers**

| Header          | Value             | Required? | Description                       |
| --------------- | ----------------- | --------- | --------------------------------- |
| `Authorization` | `<SBL_authToken>` | Yes       | Your SBL authentication token     |
| `Label-Type`    | `application/pdf` | No        | Set to get a PDF label (optional) |

**Request Body**

Send a JSON object with order details:

```json POST /api/order:createLabel
{
  "order": {
    "shipping_method": "Standard",
    "recipient": {
      "name": "Test Test",
      "email": "johndoe@shipbob.com",
      "phone_number": "444-333-2222",
      "address": {
        "address1": "223 E 5th St",
        "address2": null,
        "company_name": null,
        "city": "Greenville",
        "state": "NC",
        "country": "US",
        "zip_code": "27957"
      }
    },
    "location_id": 33,
    "reference_id": "101",
    "measurements": {
      "total_weight_oz": 4,
      "length_in": 2,
      "width_in": 4,
      "depth_in": 6
    },
    "products": [ // optional
      { "name": "Light Roast Coffee", "sku": "LIGHT-ROAST", "quantity": 1 }
    ],
    "tags": [ // optional
      { "name": "size", "value": "small" }
    ],
    "requires_signature": true, // optional
    "insurance_amount": 400, // optional
    "packing_slip": true // optional
  },
  "meta": {
    "order_number": "101",
    "order_id": "101",
    "customer_name": "ABC Merch"
  }
}
```

**Key Fields**

| Field                | Type      | Required | Description                                                                                                       |
| -------------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `shipping_method`    | string    | Yes      | Shipping option (e.g., `"Standard"`)                                                                              |
| `recipient`          | object\[] | Yes      | Recipient details (see Recipient table)                                                                           |
| `location_id`        | integer   | Yes      | ShipBob location ID. Sandbox: always use `33` or `19`. Production: contact your ShipBob rep for your location ID. |
| `reference_id`       | string    | Yes      | Unique order identifier                                                                                           |
| `measurements`       | object    | Yes      | Package dimensions and weight. All values must be whole numbers. Weight in ounces.                                |
| `meta`               | object\[] | Yes      | Extra information for your records                                                                                |
| `products`           | object\[] | No       | Pass products to print pick lists and use batching                                                                |
| `requires_signature` | boolean   | No       | `true` / `false`                                                                                                  |
| `insurance_amount`   | number    | No       | Amount in dollars. If `>= 300`, `requires_signature` automatically becomes `true`.                                |
| `packing_slip`       | boolean   | No       | `true` / `false`                                                                                                  |
| `tags`               | object\[] | No       | Key/value tags                                                                                                    |

**Response**

On success (HTTP 200):

```json
{
  "interim_order_id": "67c8a7f30c3c1d16d05179db",
  "reference_id": "101",
  "shipment_id": 100000001,
  "label": "<label_data>"
}
```

* `label`: ZPL string or PDF data (based on `Label-Type`).

**Error Responses**

* `400`: Bad request (check your JSON).
* `401`: Invalid or missing `SBL_authToken`.
* `500`: Server issue—try again later.

## Bulk Cancel Labels

`POST /api/order:bulk-cancel`

You can use this endpoint to refund or cancel shipping labels. Additionally, it allows you to cancel and resubmit one or more orders using the same `reference_id`. Once an order is canceled through this endpoint, it can be resubmitted as needed. However, please note that canceled orders will no longer be accessible in the UI or via the API.

**Headers**

| Header          | Value              | Required? | Description                   |
| --------------- | ------------------ | --------- | ----------------------------- |
| `Authorization` | `<SBL_authToken>`  | Yes       | Your SBL authentication token |
| `Content-Type`  | `application/json` | No        | Accepted content type         |

**Request Body**

Send a JSON object with order details:

```json POST /api/order:bulk-cancel
{
  "reference_ids": ["ORDER-1","ORDER-2"]
}
```

## Sync Tracking Numbers

<Tabs>
  <Tab title="Option 1 - Webhook">
    To receive tracking updates, subscribe to the `order.shipment.tracking_received` webhook that fires usually within 5 minutes after creating a shipping label.

    Learn how to subscribe [here](http://developer.shipbob.com/logistics/webhooks).
  </Tab>

  <Tab title="Option 2 - Polling">
    Sync tracking numbers back to your system using the polling-based approach.

    <Steps>
      <Step title="Fetch Orders with Tracking">
        * **Endpoint**: `GET https://api.shipbob.com/2026-01/order?HasTracking=true&IsTrackingUploaded=false`
        * **Optional Parameter**: Add `&limit=250` for up to 250 results.
        * **Header**:`Authorization: Bearer <Personal_Access_Token>`
        * **Response Example**:

        ```json highlight={8-13}
        [
          {
            "id": 234567890,
            "reference_id": "101",
            "shipments": [
              {
                "id": 100000001,
                "tracking": {
                  "carrier": "OnTrac",
                  "tracking_number": "D10010000000000",
                  "carrier_service": "Ground",
                  "tracking_url": "https://www.ontrac.com/tracking/?number=D10010000000000"
                }
              }
            ]
          }
        ]
        ```

        ####
      </Step>

      <Step title="Iterate through each order">
        * Each order has 1 shipment with ShipBob Logistics
      </Step>

      <Step title="Sync Tracking">
        * Extract the `tracking_number` from the shipments array and update your system.
      </Step>

      <Step title="Mark shipments as uploaded">
        * **Endpoint**: `POST https://api.shipbob.com/2026-01/shipment:batchUpdateTrackingUpload`
        * **Header**:`Authorization: <Personal_Access_Token>`
        * **Body**:

        ```json
          {
            "is_tracking_uploaded": true,
            "shipment_ids": [100000001, 100000002, 100000003]
          }
        ```
      </Step>

      <Step title="Repeat">
        * Poll every 15 to 30 minutes to stay updated.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Tips for Success

* Test in the sandbox first (use `location_id: 33` for label creation).
* Generate your Personal Access Token in the ShipBob dashboard for `sandbox-api` or `api.shipbob.com` calls.
* Contact your ShipBob rep for your production `location_id` or if you hit a 401 error with your `SBL_authToken`.
* Poll at least every 30 minutes to avoid missing tracking updates.

## Diagram

```mermaid
sequenceDiagram
    title ShipBob Logistics Integration Diagram
    autonumber
    participant Client
    participant ShipBob API

    Client->>ShipBob API: POST /api/order:createLabel
    activate ShipBob API
    ShipBob API-->>Client: 201 Created (labelUrl, shipmentId)
    deactivate ShipBob API

    note over Client,ShipBob API: Prereq (one-time): Client registers tracking_received webhook

    rect rgba(230,255,230,0.6)
    ShipBob API-->>Client: tracking_received (shipmentId, tracking number, url, carrier)
    Client->>Client: Upsert trackingNumber into system
    end

    opt Fallback (only if webhook unavailable)
        loop Every 15 min
            Client->>ShipBob API: GET /2026-01/order?HasTracking=true&IsTrackingUploaded=false
            ShipBob API-->>Client: 200 OK (orders with tracking)
        end
        Client->>Client: Upsert trackingNumber into system
    end

```

## FAQs

<Accordion title="How to sign up for a sandbox account?">
  Sign up for a sandbox by following [this link](https://webstage.shipbob.dev/app/merchant/#/SignUp?utm_source=app_partner).
</Accordion>

## Other Resources

* Rate Shopping API: [view here](https://developer.shipbob.com/logistics/rate-shopping)
* ShipBob Logisitics webhook: [view here](https://developer.shipbob.com/logistics/webhooks)