AAvamartech / Shopify × Claude
Educational review · not a deployment recipe

Shopify × Claude,
with control.

Claude may help interpret a bounded input or draft a proposal. It never receives a client secret, access token, unrestricted customer export, or authority to change a store. A deterministic application enforces identity, tenant, scopes, caps, approvals, and audit before it talks to Shopify.

Reviewed 31 Aug 2026 Shopify Admin API 2026-07 Synthetic and development-store tests Every external effect needs exact approval

Boundary first. The examples are architecture patterns and fictional payloads. Verify the current Shopify API version, auth route, scopes, protected-customer-data requirements, messaging rules, and applicable law for your implementation.

No implied results. This guide makes no promise about conversion, savings, delivery time, app review, income, staffing, or business outcomes.

01

Choose a path by authority

Start with the least consequential surface that can answer the learning question. The path changes the auth, data, review, and isolation obligations.

Recommended starting point

Prove the task before connecting the store

Use generated catalog, order, inventory, and event fixtures. Freeze representative, boundary, malformed, and adversarial cases. Measure grounded accuracy, schema validity, refusal, accessibility, and reviewer effort.

Exit gate

A scoped task contract, accepted synthetic eval suite, prohibited-data list, responsible owner, and documented reason a live connection is necessary.

02

The non-negotiable architecture

The model is a proposal component. It does not authenticate to Shopify, choose its own tenant, retrieve secrets, or execute network calls.

Authenticated app UIserver-derived user + tenant
Claude plannerminimized context; proposal schema only
Diff + human approvalexact immutable effect
Credentialed executorsecret manager; caps; Shopify allowlist
model: no secretsmodel: no access tokensmodel: no merchant selectionmodel: no live networkexecutor: no free-form intentapproval: invalid after any diff change
Model-facing context

Typed and minimized

  • Only fields allowed by the use-case contract and tenant policy.
  • Source IDs and versions, never credential values.
  • Untrusted store text is evidence, not instruction; prompt injection is surfaced.
  • Output is a strict proposal with citations, assumptions, uncertainty, and refusal state.
Executor-facing request

Verified and deterministic

  • Signed internal request from the reviewed application service.
  • Tenant, actor, operation, object IDs, exact variables, cap, approval hash, and stable idempotency key.
  • Token resolved server-side from encrypted tenant storage.
  • Shop domain, scope, state, rate budget, and approval revalidated immediately before execution.

Code generation is not an exception. Claude can draft application code, but generated code is untrusted. Review dependencies, auth, data flows, GraphQL cost, errors, tests, deployment configuration, and rollback before it reaches any environment.

03

App identity is not merchant authority

Keep the identities and scopes distinct in the design, storage model, UI, and audit trail.

ObjectWhat it provesWhere it livesWhat it does not prove
Client IDWhich app is askingConfiguration; it is not a secretMerchant approval or permitted resources
Client secretApp authenticity in applicable server flows and HMAC verificationServer-side secret manager onlyWhich merchant the current user may act for
Installation / access tokenInstalled app authority for one shop and its approved scopesEncrypted, tenant-keyed server storage or short-lived memoryApproval for a particular write or message
App user/sessionWhich person is using the app and, where supported, staff contextVerified server sessionPermission beyond app RBAC and Shopify’s grant
Human approvalOne authorized person accepted one immutable proposed effectAppend-only approval recordAuthority for a changed, expired, broader, or later operation
Embedded app

Token exchange

Shopify’s current templates handle the flow. Verify the ID token and exchange it on the server. Use online or offline access according to the user-attribution and background-job requirement.

Standalone / API-only

Authorization code grant

Redirect the merchant for approval, bind and verify OAuth state, require exact redirect URLs, and store the resulting shop-scoped token under that tenant.

Same organization only

Client credentials grant

Use only for server integrations acting on stores in your own Shopify organization. It is not a shortcut for client or unrelated merchant stores.

Scope discipline and least privilege. Request only the minimum scopes required by named operations. Shopify documents that a write scope includes read access for that resource. A scope grant is a ceiling, not an instruction to use it.

04

Every effect follows one write protocol

Product edits, tags, collections, discounts, themes, messages, exports, and publishes all use the same preview-and-approval contract.

Read a fresh snapshot

The executor fetches the current object version and permitted fields. Stale cached state cannot be the basis of a write.

Create a bounded proposal

Claude may suggest exact candidate values. Deterministic code validates types, IDs, limits, claims, rights, and policy.

Render the full immutable diff

Show before, after, affected tenant/resources, side effects, recipient, channel, schedule, timezone, cap, reversibility, and residual risk. No hidden fields.

Obtain exact preapproval

An authorized person approves the cryptographic hash of that proposal. Any content, variable, object, recipient, time, or scope change invalidates approval.

Revalidate and execute once

The executor rechecks tenant, scopes, current state, approval, expiry, cap, consent where relevant, and stable idempotency ledger before issuing the bounded API call.

Reconcile and record

Read back the result, compare it with the approved effect, append the response and request IDs to the audit trail, and stop on ambiguity. Do not blindly retry a timed-out mutation.

{
  "proposal_id": "{UUID}",
  "tenant_id": "{SERVER_DERIVED_TENANT}",
  "actor_id": "{AUTHENTICATED_USER}",
  "operation": "{ALLOWLISTED_OPERATION}",
  "resource_ids": ["{SHOPIFY_GID}"],
  "before_hash": "{CURRENT_SNAPSHOT_HASH}",
  "after": {"{FIELD}": "{PROPOSED_VALUE}"},
  "full_diff": [{"path": "{FIELD}", "before": "{VALUE}", "after": "{VALUE}"}],
  "cap": {"max_objects": "{APPROVED_LIMIT}", "max_value": "{APPROVED_LIMIT}"},
  "idempotency_key": "{TENANT}:{OPERATION}:{STABLE_BUSINESS_KEY}",
  "expires_at": "{ISO_8601}",
  "timezone": "{IANA_TIMEZONE}",
  "approval_hash": "{HASH_OF_ALL_FIELDS_ABOVE}",
  "status": "AWAITING_HUMAN_APPROVAL"
}

Never

  • Approve a vague batch such as “optimize the catalog.”
  • Let the model choose a shop, scope, recipient, amount, or schedule.
  • Reuse approval after a diff changes.
  • Retry an uncertain mutation without reconciliation.
  • Treat “draft” creation as harmless; drafts are still writes.

Always

  • Use operation-specific allowlists and small server-side caps.
  • Bind idempotency to a stable business operation, not a retry timestamp.
  • Record exact input/output hashes with secrets and unnecessary personal data redacted.
  • Provide stop, revoke, manual fallback, and rollback or compensating-action ownership.
05

Webhooks are untrusted, duplicate, and unordered

A webhook is an event signal. It is not authorization for Claude to decide or for the executor to create a downstream effect.

Verify before parsing

Capture the raw body; verify X-Shopify-Hmac-SHA256 with the app secret using a constant-time comparison. Reject an invalid signature. Only then trust and normalize the topic and shop domain.

Apply replay and tenant gates

Resolve the shop to an installed tenant, allowlist topic/version, enforce an application-defined replay window using verified delivery timing, and reject disabled or deleted tenants.

Deduplicate durably

Use X-Shopify-Webhook-Id in a tenant-keyed idempotency ledger. Acknowledge promptly only after durable enqueue; process outside the request path.

Handle order and poison safely

Shopify does not guarantee ordering. Compare event/resource timestamps, make handlers idempotent, cap retries, and move poison events to a tenant-isolated dead-letter queue for review.

Reconcile from source

Periodically query Shopify for updates since the last safe checkpoint. Repair local state deterministically and require a new proposal/approval for any external effect.

Compliance lifecycle. A distributed app must implement Shopify’s required privacy webhooks where applicable, including data request, customer redaction, and shop redaction. Route export/deletion across every tenant-keyed store, cache, queue, index, log, and backup policy; preserve only records a documented legal obligation requires.

06

People are not risk scores or message targets

Customer data needs minimization, an authorized purpose, correction paths, and channel-specific consent. Fluent generated text does not create permission.

Retired pattern: row-level “customer-service risk”

Do not label a person or order as risky from address mismatch, payment retries, refund history, location, language, or other proxies. Do not use model output to deny service, change price, suppress an entitlement, delay fulfillment, prioritize fraud action, or otherwise disadvantage a person.

Permitted teaching example

Authorized aggregate support triage

Report issue volumes by approved topic and time window, with minimum cohort sizes and no names, contact details, row-level scores, sensitive characteristics, or adverse action. A support lead reviews categories, can correct them, and decides staffing or documentation changes.

Protected data gate

Minimize before retrieval

Use only the fields necessary for the merchant-approved function. Complete Shopify’s protected-customer-data requirements and any applicable review. Keep test and production separate, limit staff access, log access, define retention, and operate an incident policy.

WhatsApp / SMS send gate

Drafting is not sending. The model may draft a candidate message from approved facts. A separate validator and person review claims, tracking URL, language, consent, and recipient. The credentialed messaging executor runs only after the exact send proposal is approved.

07

Multi-tenancy must exist below the prompt

A folder per shop, a store selector, or “only use this merchant’s data” in system instructions is not isolation.

LayerRequired tenant bindingFailure to test
AuthenticationVerified installation maps normalized shop domain to immutable internal tenant_id; user membership is server-derived.Forged shop parameter, stale session, user from tenant A selecting tenant B.
AuthorizationRBAC/ABAC policy checks tenant + actor + operation + resource + scope on every request and job.Valid token with wrong internal role; confused-deputy request.
Secrets & encryptionAccess tokens encrypted with tenant-bound envelope context and separately revocable references.Swapped ciphertext, wrong key context, secret in logs or model trace.
Database & objectsTenant key on every row/object; enforced query policy and unique keys include tenant.Missing filter, guessed ID, cross-tenant join, backup restore leakage.
Queues & idempotencyTenant carried in signed job envelope; tenant-keyed queue/DLQ and idempotency ledger.Retry under another tenant, duplicate event, poison job exposure.
Cache & retrievalTenant and source version in cache/vector keys; authorization filters run before retrieval.Cache key collision, cross-tenant semantic result, stale permission.
Logs & ratesTenant-tagged, redacted audit; per-tenant budgets plus global protection.Noisy tenant starvation, queryable personal data, secret header capture.
Export & deletionIdempotent tenant-scoped workflow reaches primary data, derived indexes, caches, queues, and policy-governed backups.Partial deletion, another tenant in export, uninstall leaving active jobs/token.

Isolation test gate: run positive and negative tests for every layer, including concurrent jobs, replay, uninstall, token rotation, restore, export, deletion, and incident tooling. A single cross-tenant read or effect blocks release.

08

Experiments are preregistered, not improvised

Claude may draft a hypothesis or variant. It cannot silently create a traffic split, choose success after seeing results, or publish a theme.

Preregister before building

  • Owner, decision, falsifiable hypothesis, audience, eligibility, exclusions, and unit of randomization.
  • Primary metric, guardrails, attribution window, analysis method, sample plan, and stopping rule.
  • Start/end placeholders {START_LOCAL}, {END_LOCAL}, and {IANA_TIMEZONE}.
  • Rights, privacy, consent, accessibility, localization, and interference risks.

QA before traffic

  • Assignment persistence, allocation, exposure logging, bot/staff exclusion, and analytics parity.
  • Responsive and RTL checks, performance, broken links, checkout path, and rollback snapshot.
  • Draft-theme or isolated environment first; no unsupported claim that Shopify supplies a universal experimentation feature.
  • Exact human approval for traffic activation and a separate exact approval for final publication.
experiment_id: {ID}
hypothesis: {FALSIFIABLE_STATEMENT}
population_and_exclusions: {DEFINITION}
randomization_unit: {UNIT}
variants_and_rights: {CONTROL_AND_CANDIDATES}
primary_metric: {ONE_PREDEFINED_METRIC}
guardrails: {SAFETY_QUALITY_BUSINESS_METRICS}
analysis_and_stopping_rule: {PREDEFINED_METHOD}
window: {START_LOCAL} → {END_LOCAL}
timezone: {IANA_TIMEZONE}
activation_approval_hash: {EXACT_TRAFFIC_PLAN_HASH}
publish_approval_hash: {EXACT_WINNER_DIFF_HASH}
09

Six bounded teaching patterns

Each example uses fictional data, preserves review, and makes the external effect explicit.

Read-only catalog quality report

Deterministic code validates product fields, duplicates, currencies, and totals. Claude may summarize the exception list with source IDs. Output is a report; no tag, price, product, or collection is changed.

Tests: empty catalog, malformed money, stale version, prompt injection in description, inaccessible product, and cross-tenant ID.

Product-description proposal

Use an approved fictional brief and rights-cleared product facts. Return claims with evidence, uncertainty, locale, and accessibility checks. Render the full field diff; exact human approval is required even to create a Shopify draft.

Collection-membership proposal

Business rules and membership calculations run deterministically. Claude may explain edge cases. Preview every add/remove with source data, cap the object count, bind stable idempotency, and require exact approval before the executor writes.

Aggregate support-topic triage

Use authorized, minimized, de-identified aggregates above a minimum cohort size. Produce issue themes and uncertainty for a support lead to correct. No individual risk label, adverse decision, recipient selection, or automated outreach.

Shipping-message proposal

Join order status and tracking deterministically for one intended recipient. Claude drafts from approved facts. At send time, recheck consent, purpose/category, suppression, template, locale, quiet hours, cap, and exact recipient/message/time approval.

Theme experiment proposal

Start with a preregistration. Generate variants in an isolated draft, run technical/accessibility/analytics QA, and obtain exact activation approval. Analyze the predefined metric with uncertainty; publication is a new diff and approval.

10

Release gates and failure drills

Use a development store and synthetic fixtures. Passing a happy-path demo is not evidence of safe operation.

SuiteCasesBlocking expectation
Auth & scopesWrong audience/destination/state, revoked install, missing scope, online/offline mismatch, client credentials on unrelated shop.Fail closed; no token, data, or executor call reaches the model.
Tenant isolationForged shop, guessed resource, cache collision, queue replay, swapped ciphertext, export/delete under another tenant.Zero cross-tenant reads, writes, logs, prompts, or effects.
Proposal & approvalChanged diff, expired approval, broader batch, forged approver, stale before-state, cap breach.Executor rejects before Shopify request.
Idempotency & ambiguityDuplicate click, timeout after commit, worker retry, partial batch, concurrent proposal.One stable business effect or stop + reconcile; never blind replay.
WebhookBad HMAC, parsed-before-verify, replay, duplicate ID, out of order, disabled tenant, poison payload, missed interval.Reject/quarantine/dedupe; reconcile from Shopify; no derived external action.
MessagingNo consent, wrong category, suppressed recipient, opt-out race, quiet hours, changed template, provider retry.No send; preserve clear reason and human support path.
Model safetyPrompt injection in product/order text, fabricated source, wrong schema, secret request, unsupported claim.Refuse or return review state; validators reject invalid meaning.
ExperimentBroken assignment, analytics mismatch, inaccessible variant, unauthorized traffic, post-hoc metric, publish without new approval.Do not activate/publish; revert draft and investigate.
Privacy lifecycleData request, customer/shop redaction, uninstall, retention expiry, backup restore.Complete tenant-scoped export/deletion workflow with auditable exceptions.
Stop

Kill effects first

Disable executor operations per tenant and globally, revoke affected credentials, pause queues, isolate proposals, and preserve approved audit evidence without copying sensitive content.

Investigate

Reconcile source state

Determine what Shopify and messaging providers actually committed. Notify security, privacy, domain, merchant-support, and legal owners according to the incident plan.

Recover

Rollback or compensate

Restore the last known-good configuration or manual process. Some external effects cannot be rolled back; define compensating action and customer remedy. Rerun the full suite before re-enabling.

11

Operate versions and deployments deliberately

Keep application code, Shopify configuration, prompts, policies, schemas, and evaluation fixtures under separate but linked versions.

12

Current primary references

Dated claims above were reviewed on 31 Aug 2026. Open the live source before implementing.