Skip to main content

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.

Required scope: integrations:write

Grant 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​

Created

Response Headers
    Content-Type