# Shopify

Source module: `app/connectors/shopify.py`. Kind: **facts** only. Display name: "Shopify".

The order system in the flagship refund story: the agent refunds in Stripe and the order must show as cancelled
here. The connector reads orders changed since the watermark through the Admin GraphQL API and turns each into a
state fact plus event facts, keyed by the order's numeric id, which is what an agent's tools see.

## Auth and scopes

| Item | Value |
|---|---|
| Method | Admin API access token of a custom app, sent as `X-Shopify-Access-Token`, against `https://{shop}/admin/api/{version}/graphql.json` (version `2026-07`; override with `api_version` in the credentials) |
| Credentials stored (encrypted) | `shop` (the `*.myshopify.com` domain), `access_token`; optional `api_version` |
| Least-privilege scopes | **read_orders**. Add **read_customers** only if you want customer identities hashed for cross-system linking; without it Shopify refuses the `customer` field with `ACCESS_DENIED`, the connector sends the orders query again without it, `customer_hid` is null, and the connection's health says so. Nothing else. |
| Connection test | `{ shop { name myshopifyDomain } }` |
| How to get the token | Settings → Apps and sales channels → Develop apps → Create an app → Configure Admin API scopes (read_orders) → Install app → Reveal the Admin API access token once |

## Fields pulled and why

One query, `orders(first: 100, after, query: "updated_at:>='<watermark>'", sortKey: UPDATED_AT)`, paged by cursor:

| Field | Used for |
|---|---|
| `legacyResourceId`, `id`, `name` | Subject id (numeric order id), `order_name` attribute |
| `createdAt`, `updatedAt` | State fact timestamp, watermark |
| `cancelledAt`, `cancelReason` | `order_cancelled` fact |
| `displayFinancialStatus`, `displayFulfillmentStatus` | State attributes and the derived `status` |
| `customer.email` | HMAC-hashed into `customer_hid`; the email is discarded |
| `refunds { id createdAt totalRefundedSet { shopMoney { amount currencyCode } } }` | `refund_created` facts |
| `fulfillments { id createdAt status }` | `fulfillment_created` facts |

Line items, addresses, names, phone numbers, notes, payment details and metafields are never requested.

## Fact types produced

Subject id is the numeric order id (`10231`), subject kind `order`.

| `fact_type` | When | Attributes | `raw_ref` |
|---|---|---|---|
| `order_status` | Every order returned (one per `updatedAt`) | `status` (`open`, `cancelled`, `refunded`, `partially_refunded`), `financial_status`, `fulfillment_status`, `order_name`, `customer_hid` | `shopify:order:{id}:status:{updatedAt}` |
| `order_cancelled` | `cancelledAt` set | `reason`, `customer_hid` | `shopify:order:{id}:cancelled` |
| `refund_created` | Each refund on the order | `amount` (major units), `currency`, `customer_hid` | `shopify:refund:{refund_id}` |
| `fulfillment_created` | Each fulfilment | `status` | `shopify:fulfillment:{fulfillment_id}` |

`status` is derived from fields Shopify reports and nothing else: cancelled when `cancelledAt` is set, else the
refund state from the financial status, else `open`. The library `refund_workflow` template's precondition
`state_before_action: {source: shopify, type: order_status, where: {status: eligible}}` is a placeholder for your
own policy: with this connector write it against the real fields, for example
`where: {financial_status: paid}` or `where: {status: open}`.

## Incremental sync, watermark, throttling

- First sync reads every order; later syncs add `updated_at:>='<watermark>'`. The watermark is the newest
  `updatedAt` seen, then advanced to the sync time less the safety margin like every connector.
- Shopify throttles GraphQL by query cost with HTTP 200 and a `THROTTLED` error; the connector backs off and
  retries up to six times. HTTP 401/403 marks the connection for re-authentication.
- Upserts are idempotent on `raw_ref`; a re-sync changes nothing that did not change.

## Claims produced

None.

## Limitations

- Orders only. Draft orders, returns (as distinct from refunds), inventory and customer records are not read.
- `refund_created` carries the refund's total; per-line refund detail is not read.
- Orders archived or deleted in Shopify stop appearing in `updated_at` queries; facts already written remain.