Update Integration
PUT/api/shopify/:integrationInstance
Updates a Shopify integration instance. All fields are optional - send only what you want to change.
This endpoint currently requires session authentication; Personal Access Token scope support is in progress.
Authentication: Requires Bearer token.
PATCH is also accepted at this URL. With PATCH, nested connection_settings and integration_settings objects are deep-merged with the stored values (JSON merge semantics), while PUT replaces each settings object you provide. Inventory location arrays are always replaced in full, never merged.
Side effects: changing start_date re-anchors order syncing; changing store_id re-links the sales channel's store; changing the pricing master or inventory settings queues background cache rebuilds; toggling the accounting sync flags re-evaluates which historical transactions sync to accounting.
Body fields:
- name (string): display name (must stay unique).
- connection_settings (object): url (https, no trailing slash), consumer_key, consumer_secret (custom-app modes only).
- integration_settings (object): start_date (Y-m-d, must be on/after the inventory start date), store_id, auto_link_products, auto_create_products, sales/cogs/shipping_revenue/shipping_refund/sales_returns_allowances_nominal_code_id, pricing, inventory, emailCustomers, proforma_marketplace_cost_percentage, proforma_payment_cost_percentage, sync_sales_order_invoices_to_accounting, sync_sales_credit_to_accounting, download_archived_products, download_draft_products, download_unlisted_products, shipping_method_field (title|code), override_shipping_method, fallback_shipping_method_id (id of a shipping method applied when a Shopify order has no resolvable shipping method), pickup_sync (sync_ready_for_pickup, notify_customer_ready_for_pickup, notify_customer_picked_up), settings (nested, e.g. orders.delivery_ship_dates), orders (e.g. hold_and_ship_by_date), returns (return receipt sync), allow_negative_inventory.
- is_automatic_sync_enabled (boolean).
- use_location_mapping_for_new_orders (boolean): route new orders to warehouses via location mappings.
integration_settings.cost_sync.fallback_to_default_cost (boolean): when a product has no average cost, fall back to its default cost for the cost push.
Shop URL lock: once Shopify has granted an access token for the instance, connection_settings.url can no longer be pointed at a different store and a 422 is returned naming the store it is currently connected to. The token belongs to the store that issued it, so repointing the domain underneath it would read one store's data with another store's credentials. Reset the connection first (POST /api/shopify/{integrationInstance}/reset-connection), then save the new address. Re-saving the same store in a different shape (scheme, casing, or an admin address) is not treated as a repoint, and an update that does not include connection_settings.url is unaffected.
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 Entity
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.