ShipBob Logistics API

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. After signing up, reach out to your ShipBob representative and they’ll guide you through the process and provide the necessary credentials.

Base URLs

https://logisticslabelprintingapi.shipbob.com

Authentication

Authentication depends on the API you’re calling:

Authorization: <SBL_authToken>

Authorization: <Personal_Access_Token>
Authorization: Bearer <Personal_Access_Token>

Authorization: Bearer <OAuth_Access_Token>

grant_type=authorization_code
code=<authorization-code>
redirect_uri=<your-registered-callback-url>
client_id=<your-client-id>
client_secret=<your-client-secret>
code_verifier=<pkce-code-verifier>

Authorization: Bearer <Personal_Access_Token>

Create an Order and Purchase a Label

POST /api/v1/CreateOrderAndPurchaseLabel

Creates a packed order and purchases its final-mile carrier label in a single synchronous call, returning the carrier, tracking number, and a URL to the label.

Headers

Request Body

{
  "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": [
      { "name": "Light Roast Coffee", "sku": "LIGHT-ROAST", "quantity": 1 }
    ],
    "label_file_format": "PNG", // optional
    "requires_signature": true  // optional
  },
  "meta": {
    "order_number": "101",
    "order_id": "101",
    "customer_name": "ABC Merch"
  }
}

Key Fields

Response

On success (HTTP 200):

{
  "interim_order_id": "67c8a7f30c3c1d16d05179db",
  "reference_id": "101",
  "shipment_id": 100000001,
  "final_mile_label": {
    "carrier": "OnTrac",
    "carrier_service": "Ground",
    "tracking_id": "D10010000000000",
    "tracking_url": "https://www.ontrac.com/tracking/?number=D10010000000000",
    "label": {
      "file_type": "PNG",
      "url": "https://.../label.png"
    }
  }
}

• tracking_url may be null if the carrier URL is not yet available. This is never fatal — the label is still valid.

Error Responses

400 responses include the failing fields:

{
  "error": "Invalid request to create order and purchase label.",
  "messages": ["\"order.measurements.length_in\" must be a positive number"],
  "fields": ["order.measurements.length_in"]
}

How This Differs From POST /api/order:createLabel

Both endpoints create a ShipBob order and return a shipping label, and both produce a normal ShipBob shipment. Choose based on how much of the order you know upfront:

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

Request Body

Send a JSON object with order details:

{
  "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

Response

On success (HTTP 200):

{
  "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 credentials (SBL_authToken, PAT, or OAuth 2.0 access token).
• 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

Request Body

Send a JSON object with order details:

{
  "reference_ids": ["ORDER-1","ORDER-2"]
}

Sync Tracking Numbers

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

FAQs

Other Resources

• Rate Shopping API: view here
• ShipBob Logisitics webhook: view here