Skip to main content

Update Integration

PUT 
/api/shopify/:integrationInstance

Updates a Shopify integration instance. All fields are optional - send only what you want to change.

Not yet available to API tokens

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; hold_channel_fulfillment: enabled (boolean, default false) + date_source (ship_by_date|hold_until_date) — when enabled, defers pushing the fulfillment and tracking back to Shopify until the order's ship day, so Shopify's shipment notification email is sent on the ship day rather than when the label is printed; orders with no date, or a date that is today or already past, push immediately), 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.

integration_settings.fallback_pickup_shipping_method_id (integer, nullable): the shipping method used for Click & Collect items of an order that mixes shipping and in-store pickup, when the pickup option's name isn't mapped. Must be a pickup shipping method; any other method returns 422 "The fallback pickup shipping method must be a pickup method."

Reserve Orders by Tag: integration_settings.orders.reserve_by_tag = { enabled (boolean), tags (array of strings, max 50, each max 255, no case-insensitive duplicates) }. Matching orders import as reserved and are not sent to the shipping provider until the tag is removed in Shopify or the order is unreserved. Sending a shorter tags list replaces the stored list.

Requires the integrations.update permission.

The shop URL lock also applies when the integration was connected with a pasted Admin API access token, not only through OAuth. Reset the connection first to change the store. Legacy custom-app mode (no store-bound credential) stays editable.

Store and sales channel: new orders are created in the store of this connection's sales channel. Whenever the request includes integration_settings.store_id, the sales channel is put in that store if it is in a different one — including when the value equals the saved setting, so re-saving the same store realigns a sales channel that had drifted from it. Nothing is written when the sales channel already uses that store, and orders already imported keep their store. When the sales channel moves, the response adds two top-level keys:

  • message (string): e.g. "Settings saved. New orders will now be created in store 'Curvy AU' — the sales channel was moved from 'Placeholder'."
  • sales_channel_store_updated (object): from and to, each {id, name}; from.id and from.name are null when the sales channel had no store. Both keys are absent when the sales channel did not move.

Request​

Responses​

OK

Response Headers
    Content-Type