Skip to main content

Update Sync Controls

PATCH 
/api/integration-instances/:integration_instance/sync-controls

Apply a granular, direction- and entity-aware sync-controls update for a channel integration instance. Replaces the overloaded is_automatic_sync_enabled boolean with per-capability toggles.

Required scope: integrations:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Authentication: Requires Bearer token + integrations.update permission.

All sections are OPTIONAL — send a partial PATCH and only the provided keys are merged onto the instance's current (or default) controls:

  • schedule_state — active or paused. Drives the derived is_automatic_sync_enabled coarse flag and pauses/resumes all scheduled sync.
  • capabilities — map of direction (inbound/outbound) to a map of entity (orders, products, inventory, pricing, tracking) to boolean. Capabilities outside the integration's applicable matrix are silently discarded.
  • source_of_truth — for BIDIRECTIONAL entities only (inventory, pricing): sku or channel. Non-bidirectional entries are ignored.

Returns the updated integration instance object, including sync_controls, applicable_sync_capabilities, and is_sync_schedule_paused. Each applicable_sync_capabilities descriptor carries entity, label, capability_label, is_bidirectional, plus two independent locks that tell you whether the capability can actually run.

Environment lock — environment_blocked (bool), environment_blocked_reason (string|null). true when the current backend environment refuses to run that outbound push — e.g. outside production, Amazon's production-only inventory feed, or Shopify's inventory push (unless inventory sync is enabled) and tracking push. Always false in production and for unrestricted pushes.

Availability lock — available (bool), unavailable_reason (string|null), unavailable_kind (string|null). available is false when the capability can never run, in EVERY environment including production, and unavailable_reason explains why. unavailable_kind says which case applies:

  • not_built — the capability is declared but its sync isn't implemented yet. The stored value is preserved and starts applying once the sync ships.
  • not_applicable — this specific instance's own configuration makes the sync a permanent no-op, so treat it as OFF no matter what is stored. Today this is Fulfilled-by-Faire: Faire holds the stock and produces the shipping label, so there is no inventory or tracking to push.

unavailable_kind is null whenever available is true. The two locks are independent — a capability can be environment-blocked, unavailable, both, or neither.

Accounting integrations are rejected with 400 — they use the separate accounting sync configuration.

Deprecation note: is_automatic_sync_enabled is a legacy coarse flag kept as a derived mirror of the sync-controls schedule state (sync_controls.scheduleState). New consumers should read is_sync_schedule_paused for the schedule and sync_controls for per-capability state; the legacy field is slated for rename to sync_schedule_active.

Request​

Responses​

OK