ShipBob User Management API Guide

Auth method: Personal Access Token (Bearer token) - OAuth 2.0 authorization code flow also supported for third-party integrations

Setup steps

1. Log in to the ShipBob Merchant Dashboard.
2. Navigate to Settings > API Tokens.
3. Click 'Generate New Token', provide a label, and copy the token immediately (shown once).
4. For OAuth 2.0 app integrations: register your application via the ShipBob Developer Portal to obtain a client_id and client_secret.
5. Use the authorization code flow to obtain an access token scoped to a specific merchant channel.
6. Pass the token in the Authorization header as: Authorization: Bearer

Required scopes

User object field mapping is not yet verified for this app.

List Orders

• Method: GET
• URL: https://api.shipbob.com/1.0/order
• Watch out for: Requires a channel_id context when using OAuth tokens; Personal Access Tokens default to the merchant's primary channel.

Request example

GET /1.0/order?Page=1&Limit=50
Authorization: Bearer <token>

Response example

[
  {
    "id": 12345,
    "reference_id": "ORD-001",
    "status": "Processing",
    "channel": {"id": 1}
  }
]

Get Order by ID

• Method: GET
• URL: https://api.shipbob.com/1.0/order/{orderId}
• Watch out for: Returns 404 if the order belongs to a different channel than the token's scope.

Request example

GET /1.0/order/12345
Authorization: Bearer <token>

Response example

{
  "id": 12345,
  "reference_id": "ORD-001",
  "status": "Processing",
  "shipments": []
}

Create Order

• Method: POST
• URL: https://api.shipbob.com/1.0/order
• Watch out for: reference_id must be unique per channel; duplicate submissions return a 409 conflict.

Request example

POST /1.0/order
Content-Type: application/json
{
  "reference_id": "ORD-002",
  "recipient": {"name": "Jane Doe"},
  "products": [{"id": 99, "quantity": 1}]
}

Response example

{
  "id": 12346,
  "reference_id": "ORD-002",
  "status": "Processing"
}

List Inventory

• Method: GET
• URL: https://api.shipbob.com/1.0/inventory
• Watch out for: Inventory quantities reflect fulfillable stock only; on-hand vs. committed breakdown requires per-item detail endpoint.

Request example

GET /1.0/inventory?Page=1&Limit=50
Authorization: Bearer <token>

Response example

[
  {
    "id": 500,
    "name": "Widget A",
    "total_fulfillable_quantity": 120
  }
]

Get Inventory Item

• Method: GET
• URL: https://api.shipbob.com/1.0/inventory/{inventoryId}
• Watch out for: Fulfillment center breakdown only appears if stock is distributed across multiple FCs.

Request example

GET /1.0/inventory/500
Authorization: Bearer <token>

Response example

{
  "id": 500,
  "name": "Widget A",
  "fulfillable_quantity_by_fulfillment_center": []
}

List Webhooks

• Method: GET
• URL: https://api.shipbob.com/1.0/webhook
• Watch out for: Webhooks are scoped per channel; tokens from different channels will not see each other's subscriptions.

Request example

GET /1.0/webhook
Authorization: Bearer <token>

Response example

[
  {
    "id": 77,
    "topic": "order_shipped",
    "subscription_url": "https://example.com/hook"
  }
]

Create Webhook

• Method: POST
• URL: https://api.shipbob.com/1.0/webhook
• Watch out for: The subscription_url must respond with HTTP 200 to ShipBob's validation ping or the webhook will not activate.

Request example

POST /1.0/webhook
Content-Type: application/json
{
  "topic": "order_shipped",
  "subscription_url": "https://example.com/hook"
}

Response example

{
  "id": 78,
  "topic": "order_shipped",
  "subscription_url": "https://example.com/hook"
}

Delete Webhook

• Method: DELETE
• URL: https://api.shipbob.com/1.0/webhook/{webhookId}
• Watch out for: Deletion is immediate and irreversible; no soft-delete or deactivation state exists.

Request example

DELETE /1.0/webhook/78
Authorization: Bearer <token>

Response example

HTTP 204 No Content

• Rate limits: ShipBob does not publicly document specific numeric rate limits in their developer docs as of the last known update. Throttling behavior is enforced server-side; HTTP 429 responses are returned when limits are exceeded.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: No official documentation of rate-limit headers or Retry-After behavior found. Handle HTTP 429 with exponential backoff.

• Pagination method: cursor

• Default page size: 50

• Max page size: 250

• Pagination pointer: Page and Limit query parameters; cursor-style via IDs in some endpoints

• Webhooks available: Yes

• Webhook notes: ShipBob supports outbound webhooks registered via the API or Developer Portal. Events are delivered as HTTP POST payloads to a registered subscription_url.

• Alternative event strategy: Poll GET /1.0/order with date filters for environments where webhooks cannot be registered.

• Webhook events: order_shipped, order_cancelled, order_exception, inventory_updated

• SCIM available: No
• SCIM version: Not documented
• Plan required: Not documented
• Endpoint: Not documented

Limitations:

• ShipBob does not document a SCIM 2.0 endpoint in its public developer or help center documentation.
• No SSO or IdP provisioning integrations (Okta, Entra ID, Google Workspace, OneLogin) are publicly documented.
• User/team management within ShipBob is handled exclusively through the Merchant Dashboard UI.

Three primary integration patterns are supported by the API.

First, fulfillment order sync: POST to /1.0/order per order, map the returned ShipBob order ID to your platform's reference_id (must be unique per channel

duplicates return HTTP 409), and register an order_shipped webhook for async tracking updates.

Second, inventory monitoring: poll GET /1.0/inventory (max page size 250) against reorder thresholds, supplement with inventory_updated webhooks, and reconcile periodically since webhook delivery is not guaranteed exactly-once.

Third, third-party OAuth integration: register via the ShipBob Developer Portal, obtain client_id and client_secret, and complete the authorization code flow per merchant

there is no admin-level multi-tenant provisioning API, so each merchant must authorize individually.

Sync fulfillment orders from an e-commerce platform

1. Generate a Personal Access Token in ShipBob Dashboard > Settings > API Tokens.
2. POST to /1.0/order for each new order, including recipient address and product line items.
3. Store the returned ShipBob order id mapped to your platform's order reference_id.
4. Register a webhook for order_shipped via POST /1.0/webhook to receive tracking updates asynchronously.

Watch out for: reference_id must be globally unique per channel; re-submitting the same reference_id returns HTTP 409.

Monitor inventory levels for reorder triggers

1. Call GET /1.0/inventory periodically with Limit=250 to retrieve all SKUs.
2. Compare total_fulfillable_quantity against your reorder threshold.
3. Register a webhook for inventory_updated to receive near-real-time stock change notifications.
4. On webhook receipt, call GET /1.0/inventory/{inventoryId} for the specific item's FC-level breakdown.

Watch out for: Webhook delivery is not guaranteed exactly-once; reconcile with a periodic poll to avoid missed updates.

Third-party app integration via OAuth 2.0

1. Register your application on the ShipBob Developer Portal to obtain client_id and client_secret.
2. Redirect the merchant to ShipBob's authorization URL with required scopes.
3. Exchange the returned authorization code for an access token via the token endpoint.
4. Use the access token as a Bearer token in all subsequent API requests scoped to that merchant's channel.

Watch out for: Each merchant must individually authorize your app; there is no admin-level multi-tenant provisioning API.

The channel-scoping model is the most common integration trap. A token that works for one merchant channel will silently return 404s or empty results for orders and webhooks belonging to a different channel - not an auth error, just missing data.

PATs are shown only once at generation and cannot be retrieved again, so loss requires immediate regeneration. Rate limits are not publicly documented; HTTP 429 responses are enforced server-side with no published Retry-After header, making defensive exponential backoff mandatory.

For teams building against an identity graph with 60+ deep IT/identity integrations, the absence of any SCIM endpoint or user-provisioning API means ShipBob user lifecycle must be handled entirely out-of-band from automated provisioning pipelines.