Shopify package v1.0.0

A Shopify Admin API access token held in the client's own secret manager. The stored material must be the complete X-Shopify-Access-Token header value: the token itself, with no scheme. customer_vault is the only generally-supported production custody model here — identity_federation and customer_broker are refused at startup and inline is lab-only.

Issuance depends on the app generation, and the two must not be conflated. Supported legacy credentials: apps created directly in the Shopify admin (admin-created custom apps) had Shopify pre-generate a non-expiring Admin API access token at install — Shopify documents that these apps can no longer be created, so that flow applies only to apps the deployment already operates, and it is not available to a new 2026 deployment; such tokens remain valid until the app is uninstalled or the client secret is revoked, and rotation is an external administrative action.

Current issuance and renewal flows: a new app is created in the Shopify Dev Dashboard and obtains tokens through a grant — for a server-side integration acting on the organization's own stores, the client credentials grant returns a token valid for 24 hours that is renewed by repeating the same request; embedded and standalone apps use token exchange or the authorization code grant, and Shopify directs public apps to expiring offline tokens (1-hour access token with a 90-day refresh token, and refresh retirements handled by Shopify as new tokens are acquired).

Either way an external deployment process MUST mint and renew tokens and write the fresh header value into the vault — the executor injects the stored value verbatim and performs no token lifecycle itself, and a stale value fails closed. Uninstalling the app or revoking the client secret ends a token's access (requests then return 401).

Least privilege: grant the token only the scopes these capabilities need — read_orders, read_customers and read_products for the reads, plus write_orders only if the refund-creation capability is enabled — and Shopify requires apps to be approved for protected customer data before order and customer reads return it.

Executor hygiene: the value must live only in executor memory for the lifetime of a call, must never be written to logs, traces or diagnostics, and must not appear in crash dumps; a deployment that cannot meet that bar must not enable the pack.

The endpoint host 'shopify-store.invalid' is a reserved non-production placeholder (an RFC 2606 reserved TLD): substitute the store's own host before enabling, in the endpoints, the resource locators and the egress allowlist — the allowlist matches exactly, so all three must be substituted together, and substitution is a required deployment step. The real substitution shape is '{store}.myshopify.com' (the store's myshopify.com subdomain; myshopify.com subdomains are real vendor hosts but are customer-specific, so the pack ships the reserved pattern). ORDER_ID in the refund endpoint paths is a placeholder too: refunds are sub-resources of one order, so the capability is bound to a concrete order id before enabling.

This pack pins the Admin REST API version 2026-07 deliberately: Shopify serves dated versions, and a version bump is a reviewed migration, not a silent edit. This pack registers only endpoints the official REST Admin API reference documents: listing orders, listing customers, listing products, listing an order's refunds, and creating a refund. Reads are collection reads: single-record reads (GET /admin/api/2026-07/orders/{order_id}.json, GET /admin/api/2026-07/customers/{customer_id}.json, GET /admin/api/2026-07/products/{product_id}.json, GET .../refunds/{refund_id}.json) and count endpoints are not registered by this pack.

Only the last 60 days of orders are accessible by default; older orders require the read_all_orders scope in addition to read_orders, which is a deployment decision, not a pack default.

Documented exclusions: this pack does not register order creation, update, deletion, cancellation, close or re-open (order creation through the API collects no payment, but it still records a customer-facing purchase, and cancellation moves obligations the other way), product creation, update or deletion, customer creation, update, deletion or account-invite sending, fulfillment operations, gift cards, discounts, and the entire GraphQL Admin API — Shopify marks the REST Admin API a legacy API for new public apps, and new deployments should weigh the GraphQL surface under its own review.

Refund creation is the one write in the pack because money moves: it is pay at the minimum R3 tier. Credential custody was reviewed on 2026-09-21 against this pack's custody model (an Admin API access token held in the customer's vault), with the following findings.

Issuance authority and delegation: issuance depends on the app generation, and the two must not be conflated — legacy admin-created custom apps had Shopify pre-generate a non-expiring Admin API access token at install (a flow Shopify documents as no longer creatable, so it applies only to apps the deployment already operates), while a new app is created in the Shopify Dev Dashboard and obtains tokens through a grant — the client credentials grant for a server-side integration acting on the organization's own stores, token exchange or the authorization code grant for embedded and standalone apps.

Scope: access scopes are granted per app — read_orders, read_customers and read_products for the reads, plus write_orders only if the refund-creation capability is enabled; Shopify requires apps to be approved for protected customer data before order and customer reads return it, and orders older than 60 days require read_all_orders as a deliberate deployment decision, not a pack default. Audience: no audience mechanism is documented — the token authorizes against the store's own myshopify.com host, and audience binding beyond that is not established. TTL: legacy admin-created tokens do not expire and remain valid until the app is uninstalled or the client secret is revoked; client credentials tokens are valid for 24 hours (expires_in 86399) and renewed by repeating the same request; expiring offline tokens pair a 1-hour access token with a 90-day refresh token.

Refresh ownership: an external deployment process owns minting and renewal — the client credentials grant renews by repeating the request, and Shopify handles refresh retirements as new tokens are acquired — and writes the fresh header value into the vault; the executor injects the stored value verbatim and performs no token lifecycle itself, and a stale value fails closed.

Revocation: uninstalling the app or revoking the client secret ends a token's access, with requests then returning 401. Executor access and replay/exposure: the executor reads only the vault reference; the token is replayable while valid, and its window depends on the generation — 24 hours for a new client-credentials deployment, unbounded for a legacy token until uninstall or secret revocation.

Alternate access paths: the Shopify admin UI and other apps retain access outside this pack, and uninstalling this app or revoking its client secret closes only this path. Credential custody review is complete.