Update Instance
PUT/api/shipbob/:instance
Partially update a ShipBob integration instance. Only the sections present in the request are applied; omitted sections keep their current values. The environment cannot be changed after connect. Leave api_token out to keep the stored token.
integrations:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Authentication: Requires Bearer token.
Request Body (all fields optional):
- name (string) — Unique display name.
- connection_settings (object):
- api_token (string, nullable) — New Personal Access Token (omit to keep the existing one).
- channel_id (integer, nullable) — ShipBob write channel id. A changed id is checked live against the token's write-scoped channels (ShipBob GET /channel); a channel the token cannot write is refused with 422 on connection_settings.channel_id, and the stored channel_name is taken from ShipBob.
- channel_name (string, nullable) — Channel display name.
- settings (object):
- sync_start_date (date, nullable) — Earliest order date pulled by a "from start date" order sync (Y-m-d); null means 30 days ago. A Full Re-sync ignores it.
- auto_create_products (boolean, nullable).
- record_shipping_costs (boolean, nullable).
- default_shipping_method (string, nullable).
- push_orders_enabled (boolean) — "Push orders to ShipBob" (default true). false stops SKU.io sending orders to this ShipBob account: an order routed to a ShipBob warehouse is rejected with a reason instead of being sent, including a manual submit. Use it when orders already reach ShipBob another way (for example ShipBob's own Shopify app).
- fulfillment_cost_financial_line_type_id (integer, optional, nullable) — COST financial line type for freight; omitted keeps the current value.
- billing (object, optional) — merged over the current billing settings:
- enabled (boolean) — billing sync + attribution switch (default false); turning it on fills the freight line type with the default "Shipping Cost" type when empty and queues the first billing sync.
- start_date (date, nullable) — earliest charge date synced/attributed.
- attribute_to_orders (boolean, default true)
- attribute_storage (boolean, default true)
- capitalise_receiving (boolean, default false) — write receiving fees as purchase order cost lines (landed cost) instead of a cost allocation.
- post_invoices_to_accounting (boolean, default false) — post ShipBob invoices as vendor bills.
- default_nominal_code_id (integer, nullable) — fallback expense account for posted fee lines.
- is_automatic_sync_enabled (boolean) — false pauses all scheduled syncing for the instance.
- settings.auto_sync (object, nullable) — per-entity scheduled-sync toggles: orders, shipments (also tracking), inventory, products, returns, receiving. An entity switched off is skipped by the scheduler.
settings.billing.* keys are saved one by one: sending a single billing switch leaves the other billing settings untouched. settings.billing.default_nominal_code_id is required whenever invoice posting is on after the save — settings.billing.post_invoices_to_accounting sent as true, or already on and not sent — so clearing the account on a posting instance is also rejected with 422. Settings the request does not send (including fulfillment_cost_financial_line_type_id) are left as stored; sending fulfillment_cost_financial_line_type_id: null selects the default Shipping Cost type.
Omitting fulfillment_cost_financial_line_type_id keeps the configured cost line type; send it (or null) to change it.
Re-sending the connection's current name is accepted; a name used by another connection returns 422.
Request
Responses
- 200
- 401
- 403
- 404
- 422
- 429
OK
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.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Unprocessable Content
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.