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 environment_blocked (bool) and environment_blocked_reason (string|null). environment_blocked is 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 shopify.inventory_sync_enabled) and tracking push. Always false in production and for unrestricted pushes — so the UI renders that toggle as disabled with environment_blocked_reason as the explanation.

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