Skip to main content
connic
Connectors

Shopify

Start agents from orders in a Shopify store, and let them tag orders and add notes.

Last updated
ModesInbound, outbound
YAML typeshopify
CredentialsA Connection of type shopify, with the client ID and secret of an app you create in the Shopify Dev Dashboard
BridgeNot supported
Custom domainNot supported
Linked agentsOne or more. A matching event starts every linked agent.
While pausedDeliveries get 200 and start no runs. Outbound sends nothing.

Set up

  1. In the Shopify Dev Dashboard, open Apps, click Create app, choose Start from Dev Dashboard, and name the app. The app must belong to the same Shopify organization as the store; see Shopify app and access.

  2. On the app's Versions page, leave App URL at its default and set Webhooks API version to 2026-10. Under Scopes, add read_orders for inbound connectors and write_orders for outbound ones; a write scope includes reading. Click Release.

  3. Order webhooks carry customer data. In the app's Settings, open Access requests → Protected customer data → Manage and select Customer data, plus the name, email, address, or phone fields when your agents need them.

  4. Click Install app, pick the store, and click Install. Then copy the Client ID and the Client secret from the app's Settings.

  5. In connic, open Project Settings → Connections, click New connection, and choose Shopify. You can also create the Connection from the Connection picker in the connector form. Enter a Name, the store's Shop domain, such as acme.myshopify.com (the store's name alone works too), the Client ID, and the Client secret, and click Create connection. connic asks Shopify for a token, so wrong values or an app outside the store's organization fail here.

  6. Open the agent. In Connector Flow, click Add inbound connector for order events or Add outbound connector for tags and notes. Then click Create New Connector and choose Shopify.

  7. Choose the mode, Inbound (Order events) or Outbound (Tags and notes), and pick the Connection under Connection. For inbound, enter the Topics. Click Create. An inbound connector subscribes the app to its topics now. For outbound, then choose how the agent uses the connector and click Link connector.

Configuration

The fields of a Shopify connector, the same in connectors/*.yaml, the REST API, and connic MCP. The descriptions name the matching setting in the dashboard. Connectors in code describes the fields every connector shares, such as agents and environments.

FieldTypeStatusDescription
typestringRequiredshopify.
modestringRequiredinbound or outbound. Dashboard: Mode.
connectionstringRequiredInbound and outbound. Name or ID of a Shopify Connection. Dashboard: Connection.
configobjectOptionalInbound. Shopify settings; outbound connectors have none.
topicsstring[]RequiredInbound. The order topics that start runs: ORDERS_CREATE, ORDERS_PAID, ORDERS_FULFILLED, ORDERS_PARTIALLY_FULFILLED, or ORDERS_CANCELLED. Shopify's REST names, such as orders/create, work too. Dashboard: Topics, one per line, starting with ORDERS_CREATE and ORDERS_PAID.

The shop domain, client ID, and client secret belong to the Connection, not to the connector.

Generated values

connic sets these when you save the connector.

ValueModesDescription
Webhook subscriptionsInboundThe app's subscriptions to the connector's topics in the store, for the connector's URL. connic creates them when you save the connector, so you don't set them up in Shopify.

Agent input

Modes: Inbound

An inbound connector starts a run for every linked agent each time Shopify delivers an order event for one of its topics. The run receives:

payload.json
{
  "topic": "orders/paid",
  "order": "#1001",
  "order_id": 5841234567,
  "conversation_id": "shopify:acme.myshopify.com/5841234567",
  "url": "https://acme.myshopify.com/admin/orders/5841234567",
  "raw": { ... }
}
  • topic is the topic as Shopify names it in the delivery, such as orders/create or orders/paid.
  • order is the order's name, such as #1001, and order_id its numeric ID.
  • conversation_id stays the same for every event of one order. To give the agent the order's earlier events as history, set session.key: input.conversation_id in its YAML; the connector doesn't turn on sessions by itself.
  • url is the link to the order in the Shopify admin.
  • raw is the whole order as Shopify sends it, in the app's webhook API version.

A delivery that Shopify sends again doesn't start another run. Inbound mode doesn't change the order by itself: to tag it or add a note, link the agent to an outbound Shopify connector that uses the same Connection; see Outbound delivery.

Shopify app and access

connic calls Shopify as the app you create in the Shopify Dev Dashboard and install on the store. The app and the store must belong to the same Shopify organization; otherwise Shopify gives the app no token and saving the Connection fails. Whenever connic calls Shopify, it gets a short-lived token with the client ID and secret, so there is no access token to copy or rotate.

Inbound connectors need the read_orders scope and outbound connectors write_orders, which includes reading. If a scope is missing, connic says so when you save the connector. Adding a scope takes a new released version of the app that is approved in the store. Order webhooks carry customer data, so the app also needs access to protected customer data, as in step 3 of Set up.

Shopify webhooks

Modes: Inbound

Saving an inbound connector subscribes the app to the connector's topics in the store, for the connector's URL. Changing the topics updates the subscriptions, and deleting the connector removes them.

connic checks the signature of every delivery, which Shopify makes with the app's client secret. Shopify deletes a subscription after 8 failed deliveries in a row; saving the connector again subscribes it again.

Outbound delivery

Modes: Outbound

An outbound Shopify connector changes one order each time it's used: when a linked agent's run completes, when the model calls it as a tool, or when middleware calls it, depending on the link's usage. The first rule that applies decides which order:

  1. When the output or payload sets order_id, such as 5841234567 or gid://shopify/Order/5841234567, it changes that order.
  2. When an inbound Shopify connector on the same Connection started the run, it changes the order whose webhook started it.
  3. Otherwise the delivery fails.

The changes run in this order: remove tags, add tags, then the note.

Automatic output

An automatic link uses the run's final output. A JSON object can set tags, a list or a comma-separated string of tags to add, remove_tags, a list of tags to remove, note, text added to the order note as a new line, replace_note: true to replace the note with note instead, and order_id. Plain text is added to the note.

output.json
{
  "tags": ["review", "high-value"],
  "note": "Billing and shipping country differ. Hold until the customer confirms the address."
}

Agent-tool and middleware payload

The model or middleware passes the same fields: tags and remove_tags as lists, note, replace_note, and order_id as a string. At least one of tags, remove_tags, and note is needed. Other fields are rejected.

connector-payload.json
{
  "remove_tags": ["review"],
  "tags": ["address-confirmed"],
  "order_id": "5841234567"
}

Delivery and retries

When Shopify rate-limits a change, connic waits and retries the delivery. The connector's runs show each delivery with the error, or with order_id, the url of the order, and what changed: tags_added, tags_removed, and note (appended or replaced).

Limits and errors

LimitValue
Answer to Shopifyconnic answers right away and runs the agents afterwards.
Failed deliveriesShopify retries a failed delivery over about 4 hours and deletes the subscription after 8 failed deliveries in a row. Saving the connector again subscribes it again.
API requestsWhen Shopify rate-limits a change, connic waits and retries the delivery.

Requests with a missing or wrong signature get 401. Saving a Connection fails when Shopify rejects the client ID or secret, has no store at the shop domain, or the app isn't in the store's organization. Saving a connector fails when the app lacks the scope it needs. A delivery fails when the output has no tags, tags to remove, or note, when it names no order and no Shopify connector on the same Connection started the run, or when Shopify rejects the change, for example when the order doesn't exist.