Create Instance
POST/api/shipbob
Connect a new ShipBob integration instance. The provided ShipBob Personal Access Token is stored encrypted, a per-instance webhook signing secret is generated, webhook subscriptions are registered, and an initial pull of every entity is queued: fulfillment centers, shipping methods, products and inventory always; orders (back to settings.sync_start_date), returns and receiving orders when their settings.auto_sync toggle is on.
integrations:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
ShipBob is single-instance per account: when a ShipBob connection already exists the request is refused with 422 on integration.
Authentication: Requires Bearer token.
Request Body:
- name (string, required) — Unique display name for the instance.
- connection_settings (object, required):
- environment (string, required) — 'production' or 'sandbox'.
- api_token (string, required) — ShipBob Personal Access Token.
- channel_id (integer, optional) — ShipBob write channel id (from Test Connection). When omitted, the server calls ShipBob GET /channel with the token and picks the token's only write-scoped channel (or the single Single-Merchant Application channel among several). If none is writable, or several are and none is the SMA channel, the request is refused with 422 on connection_settings.channel_id asking you to run Test Connection and choose one; a token ShipBob rejects is refused with 422 on connection_settings.api_token.
- channel_name (string, optional) — Display name of the channel (taken from ShipBob when the channel is resolved server-side).
- settings (object, optional):
- sync_start_date (date, optional) — Earliest order date for the first import (Y-m-d). Blank or omitted stores 30 days ago.
- auto_create_products (boolean, optional) — Auto-create SKU products from ShipBob products.
- record_shipping_costs (boolean, optional, default: true) — Record shipping costs from shipments.
- default_shipping_method (string, optional) — Fallback shipping method name.
- is_automatic_sync_enabled (boolean, optional, default: true) — Enable automatic background syncing.
Request
Responses
- 201
- 401
- 403
- 422
- 429
Created
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.