Skip to main content

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.

Required scope: integrations:write

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

OK

Response Headers
    Content-Type