|
1
|
--- |
|
2
|
name: shopify |
|
3
|
description: Build production Shopify storefronts on Replit for physical products, merch, inventory, stock, variants, shipping, and fulfillment. Covers Shopify Store connection setup, Storefront API for buyers, Admin API for catalog setup, Go Live transfer, and merchant-owned compliance boundaries. |
|
4
|
--- |
|
5
|
|
|
6
|
IMPORTANT: Use Shopify when the user wants to sell physical products, manage inventory, or build a Shopify-hosted storefront/checkout. Do NOT ask the user for Shopify API keys — propose the Shopify Store integration and fetch the Repl-scoped connection yourself. Shopify is the system of record for products, inventory, carts, checkout, and orders; the generated app is only the storefront UI + catalog/cart client. Execute the steps below directly. |
|
7
|
|
|
8
|
## Routing |
|
9
|
|
|
10
|
Default to Shopify, not Stripe, when the user mentions physical products, merch, merchandise, swag, apparel, inventory, stock, shipping, fulfillment, product variants, sizes, colors, Shopify checkout, or selling tangible goods. A concrete tangible product noun counts as a physical-goods signal even when the user never says "physical" — e.g. pens, shirts, mugs, books, ceramics, jewelry, candles, posters, stickers, or apparel. "Build an ecommerce site for selling pens with checkout and payments" is a Shopify request. |
|
11
|
|
|
12
|
Use Stripe instead when the user explicitly asks for custom payment processing, SaaS subscriptions, digital/downloadable goods, donations, invoices, or a non-Shopify checkout — a digital/download cue (e.g. "downloadable poster prints") overrides the product noun. A bare "store"/"storefront"/"checkout"/"ecommerce" with no physical-goods, inventory, shipping, or fulfillment cue is ambiguous: ask one short clarification before choosing Shopify vs Stripe. Do not pivot to Stripe just because a Shopify step (token minting, publication, checkout preview) is blocked — surface the Shopify blocker and continue. |
|
13
|
|
|
14
|
## Helper scripts — write these first |
|
15
|
|
|
16
|
Two reference files do all Shopify I/O. Write them to the project root from `./references/` and run via `shell_exec` (NOT `code_execution` — `process.env` connector vars are unavailable there). The OpenInt proxy injects Admin auth; never handle Admin tokens yourself. |
|
17
|
|
|
18
|
- **shopify-admin-api.mjs** (source: `./references/shopify-admin-api.mjs`) — one-off Admin GraphQL calls through the OpenInt proxy, for catalog setup only: |
|
19
|
|
|
20
|
```bash |
|
21
|
node shopify-admin-api.mjs '{"query":"query { shop { name myshopifyDomain } }"}' |
|
22
|
``` |
|
23
|
|
|
24
|
- **shopifyStorefrontClient.ts** (source: `./references/shopifyStorefrontClient.ts`) — server-side Storefront API client for buyer flows. It fetches the connection from OpenInt, extracts `shop_domain` + `storefront_access_token`, pins the API version, and exposes `shopifyStorefrontRequest<T>()`. Put it behind API routes / server actions / SSR-only modules; never read connector env vars from browser code. |
|
25
|
|
|
26
|
## Step 1: Connect |
|
27
|
|
|
28
|
1. Propose the Shopify Store integration if this Repl has no Shopify Store connection assigned (reference the `integrations` skill). The `shopify-store` connector is **app-scoped** — a connection belongs to exactly one Repl. |
|
29
|
2. `listConnections('shopify-store')` in `code_execution`, then select only a connection assigned to the current Repl/app. A connection on another Repl is NOT connected for this Repl — create a fresh one instead of reusing its ID; do not suggest switching providers. |
|
30
|
3. Fetch settings from `/api/v2/connection?include_secrets=true&connector_names=shopify-store&refresh_policy=none` with `X_REPLIT_TOKEN`. Read only `shop_domain` and `storefront_access_token` from `items[0].settings` for app code (Shopify treats the Storefront token as public buyer-facing auth). Do not surface `shop_id`, Admin tokens, or `pending_transfer` (Go Live status only) in app UI. The payload has no publication ID, claim link, or dev-store flag — resolve those at runtime. |
|
31
|
|
|
32
|
If the merchant asks to transfer/claim the store (whether at connect time or later), do not attempt it from app code — direct them to the Shopify integration's management surface in the workspace: open the **Integrations** tab, go to **Shopify** and click **Manage**. (Navigate by UI surface rather than emitting a `replit.com` URL — that surface is environment-correct in dev/staging/prod, whereas a hardcoded host would send staging/local sessions to the wrong environment.) See Step 5 for the full Go Live flow. |
|
33
|
|
|
34
|
## Step 2: Stop after connect |
|
35
|
|
|
36
|
Onboarding is done once all three hold: the connection is assigned to this Repl, the app renders a static empty/connected storefront state from placeholders, and you have asked the user what they want to sell. Do NOT, as part of onboarding: query Storefront/Admin APIs, scaffold a catalog/products route, or seed demo products/collections/inventory/publications. Everything below is explicit follow-up work, triggered only when the user asks. |
|
37
|
|
|
38
|
## Step 3: Catalog setup (Admin API, only when the user asks to add products) |
|
39
|
|
|
40
|
Run setup through `shopify-admin-api.mjs`. Setup/seed scripts are orchestration only (which products to create, which local mapping file to write); every Admin request must go through the proxy helper with `Connector-Name: shopify-store`. Do not call `https://{shop_domain}/admin/...` directly, use Admin SDK clients, or read Admin tokens. For the whole sequence, prefer copying the known-good `./references/seed-products.mjs` golden script (replace its `PRODUCTS` array, run it) rather than hand-assembling the mutations — it already implements the order, idempotency, and error handling below. |
|
41
|
|
|
42
|
See `./references/code-templates.md` → "Create, price, stock, and publish a product" for the exact GraphQL. The required order and the mutations to copy: |
|
43
|
|
|
44
|
1. Look the product up by `handle` (`productByHandle`) first and reuse its IDs if it exists; otherwise `productCreate` → product `id` (set `status: "ACTIVE"`). `productCreate` is not idempotent, so the handle check keeps re-runs from duplicating products. |
|
45
|
2. Query `product.variants` for the variant `id` (this is the Storefront cart `merchandiseId` — persist/render it, never invent IDs) and `inventoryItem { id }`. |
|
46
|
3. `productVariantsBulkUpdate` to set price. |
|
47
|
4. Inventory, in this exact order or stock is silently unenforced: `inventoryItemUpdate({ tracked: true })` → `inventoryActivate(inventoryItemId, locationId)` → read the current `available` level, then `inventoryAdjustQuantities` with a per-change `changeFromQuantity` compare-and-set. Resolve the location with `locations(first: 1)`; never hardcode it. Shopify requires the `@idempotent(key: ...)` directive at the **field** level (stable per-item key, e.g. the handle) on `inventoryActivate` and `inventoryAdjustQuantities`; omitting it fails with `The @idempotent directive is required for this mutation but was not provided`. (`inventorySetQuantities` also works but on `2026-04` dropped `ignoreCompareQuantity` and requires a per-item `changeFromQuantity`.) |
|
48
|
5. Resolve the Replit-owned publication via `currentAppInstallation { publication { id } }` (the connection payload has none) — this is the authoritative Replit Sales Channel, the same lookup the `shopify-store` connector uses. If absent, fall back to the publication named exactly `Online Store` (match the exact name, not a broad `Sales Channel` substring that would catch unrelated channels like `Google & YouTube Sales Channel`); on a transferred live store, gate that fallback behind explicit user confirmation since it exposes products on the merchant's existing storefront. Then `publishablePublish`. If neither exists, skip publishing and tell the user the Sales Channel publication is not provisioned yet. |
|
49
|
|
|
50
|
Inspect `userErrors` on every mutation and stop on the first non-empty array. Products are invisible to the Storefront API until active AND published to a storefront-visible publication. For batches >20 items use `bulkOperationRunMutation`, and throttle on `extensions.cost.throttleStatus` (the helper does not auto-throttle). |
|
51
|
|
|
52
|
## Step 4: Buyer storefront (Storefront API) |
|
53
|
|
|
54
|
Use `shopifyStorefrontRequest` from `shopifyStorefrontClient.ts` directly for buyer flows — do NOT route buyer traffic through OpenInt. See `./references/code-templates.md`: |
|
55
|
|
|
56
|
- "Query products in app code" → product/variant lists for catalog/product pages. |
|
57
|
- "Create a cart and redirect to Shopify checkout" → `cartCreate` with a ProductVariant `id` as `merchandiseId`, then `cartLinesAdd`/`Update`/`Remove`, then send the buyer to `cart.checkoutUrl`. Checkout and payment happen on Shopify — do not implement custom payment collection. |
|
58
|
|
|
59
|
Cache product responses (Storefront API allows ~60 req/min/IP); don't call it from a hot client render loop. On a 401/403, refetch the connection settings once and retry (the helper does this); if still failing, stop and report that the connector-provided `storefront_access_token` may need recreating — do not pivot to Admin draft orders, cart permalinks, or disabling the store password. |
|
60
|
|
|
61
|
**Dev-store preview:** Vibe/dev stores are password protected. If `checkoutUrl` hits the password page, keep the real cart and append `channel=online_store` (see `createCheckoutUrl`'s `useDevStorePreview` option in code-templates.md). The connection has no dev-store flag, so this is a caller-controlled option driven by environment — turn it OFF for live stores. Never ask the user to disable password protection. |
|
62
|
|
|
63
|
## Step 5: Go Live (only when the merchant asks) |
|
64
|
|
|
65
|
Do not transfer the store during build/provisioning. When the merchant asks to go live, walk the checklist and use the Shopify Store integration management actions; see `./references/code-templates.md` → "Go Live behavior". |
|
66
|
|
|
67
|
- **Store transfer:** transfer is handled by Replit's Shopify integration management surface, not by app code. When the merchant asks to claim/transfer the store, direct them to it by UI navigation rather than a `replit.com` URL: open the **Integrations** tab, go to **Shopify** and click **Manage**. (That surface is environment-correct in dev/staging/prod; a hardcoded host would send staging/local sessions to the wrong environment.) From there the transfer runs against the existing connection. Do not mint a claim link from app code, collect raw Shopify credentials, or recreate the connection (transfer mutates the existing one). Surface `pending_transfer` if useful. |
|
68
|
- **Status/deep-link only (merchant-owned in Shopify):** plan selection, Shopify Payments / gateway KYC (never collect banking/SSN/tax-ID PII), shipping zones/rates (`write_shipping` is intentionally not scoped — you may suggest starter defaults in chat but must not apply them), taxes (tell them to consult a tax professional), custom domain, and removing the storefront password / launching the Online Store. |
|
69
|
- **Legal policies:** you may draft first-pass policy text with a lawyer-review disclaimer. |
|
70
|
- After transfer, if OpenInt reports `reauthorization_required`, stop Admin writes and tell the user to reconnect via the Integrations tab; the connection ID stays stable. Stop appending the dev-store preview param once targeting the live storefront. |
|
71
|
|
|
72
|
Example response when the merchant asks to claim/transfer the store — explain it's a merchant-owned action, give the UI-navigation steps, and set expectations: |
|
73
|
|
|
74
|
> Claiming/transferring the store isn't something I can do from code — it's a merchant-owned action you start in Replit's Shopify integration surface: |
|
75
|
> |
|
76
|
> 1. Open the **Integrations** tab in your workspace (left sidebar). |
|
77
|
> 2. Find **Shopify** and click **Manage**. |
|
78
|
> 3. Start the transfer/claim flow. Shopify will email you to accept ownership of the `<shop>.myshopify.com` store into your own Shopify account. |
|
79
|
> |
|
80
|
> A few things to know: |
|
81
|
> |
|
82
|
> - The connection ID stays the same after transfer, so your storefront keeps working with no code changes. |
|
83
|
> - Once the store is live (no longer a dev store), the `channel=online_store` checkout-preview param should be turned off — tell me when the transfer is done and I'll flip the dev-store-preview flag. |
|
84
|
> - You'll still handle these yourself in the Shopify admin (they need your real identity/banking): pick a plan, set up Shopify Payments (KYC), configure shipping zones/rates, taxes, custom domain, and remove the storefront password to open the Online Store. |
|
85
|
> - If Shopify ever asks the integration to reconnect after transfer, go back to the Integrations tab and reconnect — don't delete and recreate the connection. |
|
86
|
|
|
87
|
Shopify webhooks (order created/cancelled, inventory changed) are not wired through this connector in v1 — pull data on user-driven refresh or framework cache revalidation; do not register Shopify webhooks from app code. |
|
88
|
|
|
89
|
## App configuration (for reference) |
|
90
|
|
|
91
|
The installed Sales Channel App is a channel app, so `currentAppInstallation.publication.id` is available via Admin GraphQL at setup time. Scopes: `write_products`, `write_inventory`, `read_locations`, `read_publications`/`write_publications`, `unauthenticated_read_product_listings`, `unauthenticated_read_product_inventory`, `unauthenticated_read_checkouts`/`unauthenticated_write_checkouts`. |
|
92
|
|
|
93
|
If you believe two Repls are the same app but OpenInt reports a different `repl_id`, report the two IDs and ask platform code owners to investigate — do not attach another Repl's connection. |
|
94
|
|
|
95
|
## Rules (these override anything above) |
|
96
|
|
|
97
|
- Treat Shopify as the system of record for products, inventory, carts, checkout, and orders; store only minimal local mappings (handles, product IDs, variant IDs, cart IDs). |
|
98
|
- Route every Admin write through `shopify-admin-api.mjs` (OpenInt proxy); never own Admin auth, implement Shopify OAuth, or mint Admin/Storefront tokens in app code. |
|
99
|
- Route buyer Storefront calls directly to Shopify via `shopifyStorefrontClient.ts` with the connector-provided public token; never ask the user to paste a token. |
|
100
|
- Use Shopify hosted checkout via `cart.checkoutUrl`. Do not build buyer checkout from Admin draft orders unless the user explicitly asks for invoice-style manual orders. |
|
101
|
- Do not hardcode publication, location, product, variant IDs, or shop domains — resolve them from Shopify or the connection at runtime. |
|
102
|
- Do not seed products/collections/inventory during onboarding; do not query a non-existent Admin `storefrontAccessTokens` root field. |
|
103
|
- Do not initiate transfer unless the merchant chooses Go Live; do not recreate the connection on transfer or reauthorization. |
|
104
|
- If Admin writes fail because the store was transferred or the app uninstalled, explain Shopify needs reauthorization and stop — do not ask for raw tokens. |
|
105
|
|
|
106
|
## References |
|
107
|
|
|
108
|
- `./references/shopify-admin-api.mjs` — Admin GraphQL helper through the OpenInt proxy. |
|
109
|
- `./references/seed-products.mjs` — known-good runnable catalog seed script (create/price/stock/publish; idempotent and safe to re-run). |
|
110
|
- `./references/shopifyStorefrontClient.ts` — Storefront API client (`shopifyStorefrontRequest`) for app code. |
|
111
|
- `./references/code-templates.md` — copy-ready snippets: product create/price/stock/publish, product queries, cart + checkout redirect, Go Live behavior. |