docs(shopify): explain checkout event loss and link the order sync

[posthog]

Changes

The Shopify guide tells store owners to capture checkout_completed with a custom storefront pixel. That is browser capture, and the page names none of the reasons browser capture loses orders. A merchant who compares PostHog against their own Shopify order count finds fewer orders and has no page to read. The guide also never links the Shopify data warehouse source, which already syncs orders server-side. This PR adds two subsections to "Tracking conversions" and changes no code.

Problem

• This is the only checkout tracking guidance we publish for storefronts. The failure mode is a merchant who stops trusting their conversion numbers, which is the number an ecommerce customer is here for.
• The page names no loss cause: not blocked requests, not the pixel consent gate, and not the shopper who leaves before the request sends.
• There is no expected gap, so a merchant cannot tell a normal gap from a broken pixel.
• The advice given in the absence of the page is wrong. posthog-js has no "enable sendBeacon" option, and the SDK already beacons on unload with no configuration, so a merchant who follows that advice changes nothing and still sees the gap.
• A server-side order path already exists, and the page never mentions it.

What changed

New subsection	What it gives the merchant
Why PostHog records fewer checkouts than Shopify	The three loss causes, the fix for each, a gap size that is consistent with them, and the point where a gap becomes a broken pixel instead
Reconciling with your Shopify orders	The Shopify warehouse source as the complete order count, and what each of the two paths is good for

The first subsection also states that no "enable sendBeacon" option exists, so a reader does not go looking for one.

Evidence for the beacon statements

Pinned to posthog-js 5bd67c5:

• types.ts:248 is a per-request transport field, not an init option.
• types.ts:254 disableTransport only turns transports off.
• request.ts:636 defaults the transport to fetch.
• posthog-core.ts:1376 _handle_unload flushes the queues on unload, and request-queue.ts sends that flush with sendBeacon. No configuration is involved.
• posthog-core.ts:1992 skips the beacon path for a request that has a callback, which is why a beacon cannot be the global default.

The consent statement follows Shopify's pixel privacy docs: "Shopify's pixel manager will only load your pixel if there is visitor permission for all of the settings that your pixels declares as required."

The warehouse source syncs Orders and Abandoned checkouts today, so reconciliation needed documentation only.

Before you open a PR checks

• prettier --check contents/docs/libraries/shopify.mdx passes. The repo pnpm format glob excludes MDX, so prettier ran directly on the file.
• pnpm start served /docs/libraries/shopify and the new text is present in the page data. The console shows no new errors. The only build errors are the pre-existing missing third-party API keys.
• No navigation change and no page move, so no screenshots and no vercel.json redirect are owed.

Note

Two open drafts edit the same file near the same lines and neither closes this gap: #20013 (page speed and the pixel snippet) and #20101 (events do not appear at all). This PR adds new subsections below their hunks, but whichever merges first leaves the others to rebase.

Checklist

• I've read the docs and/or content style guides.
• Words are spelled using American English
• Use relative URLs for internal links
• I've checked the pages added or changed in the Vercel preview build. I checked the page locally instead, see above. The Vercel preview still needs a check after it builds.
• If I moved a page, I added a redirect in vercel.json. No page moved.

---

Created with PostHog Desktop from this inbox report.

[github-actions]

Deploy preview

Status	Details	Updated (UTC)
🟢 Ready	View preview	Sep 15, 2026 07:59PM

Changed pages

Page	Source
Shopify	contents/docs/libraries/shopify.mdx

[github-actions]

Vale prose linter → found 1 errors, 11 warnings, 1 suggestions in your markdown

Full report → Copy the linter results into an LLM to batch-fix issues.

Linter being weird? Update the rules!

contents/docs/libraries/shopify.mdx — 1 errors, 11 warnings, 1 suggestions

Line	Severity	Message	Rule
7:66	warning	Use 'PostHog' instead of 'posthog'.	Vale.Terms
7:104	warning	Use 'Shopify' instead of 'shopify'.	Vale.Terms
9:66	warning	Use 'PostHog' instead of 'posthog'.	Vale.Terms
9:104	warning	Use 'Shopify' instead of 'shopify'.	Vale.Terms
11:18	warning	Avoid trivializing words. 'easy to' can sound dismissive to the reader.	PostHogDocs.Trivializers
16:53	warning	Use 'X' instead of 'x'.	Vale.Terms
27:69	error	Hi, Andy here... use an en dash ( – ) with spaces. On Mac, holding down the Option and hyphen key will give you an en dash.	PostHogBase.EnDash
78:132	warning	Use bold (text) for UI elements, not quotes.	PostHogDocs.UIBoldNotQuotes
88:224	suggestion	Address the reader directly. Use 'you' instead of 'the user'.	PostHogDocs.DirectAddress
182:194	warning	'webpages' is a possible misspelling.	PostHogBase.Spelling
192:221	warning	Capitalize 'Product Analytics' for PostHog's product. Use 'product analytics' for the general industry concept.	PostHogBase.ProductNames
198:16	warning	Capitalize 'Data Warehouse' for PostHog's product. Use 'data warehouse' for the general industry concept.	PostHogBase.ProductNames
230:12	warning	'regionality' is a possible misspelling.	PostHogBase.Spelling

[github-actions]

Bundle report

Total JS (gzip)

8.78 MiB (no change)

Eager graph (modules shipped in each entrypoint's initial chunks)

Entrypoint	Eager size	Budget	Modules
✅ app	18.52 MiB (no change)	report-only	2062

Largest modules in the app closure

Module	Size
./src/data/mcp-tools.json	1143.2 KiB
css ./node_modules/.pnpm/css-loader@5.2.7_webpack@5.101.3/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/postcss-loader@4.3.0_postcss@8.5.6_webpack@5.101.3/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css	774.2 KiB
./src/components/Stickers/Stickers.tsx	696.4 KiB
./node_modules/.pnpm/@radix-ui+react-icons@1.3.2_react@18.3.1/node_modules/@radix-ui/react-icons/dist/react-icons.esm.js	481.4 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/x-ray.mjs	480.8 KiB
./node_modules/.pnpm/rehype-raw@7.0.0/node_modules/rehype-raw/lib/index.js + 29 modules	395.1 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/im-the-driver.mjs	385.7 KiB
./src/hooks/useCustomers.tsx + 55 modules	370.0 KiB
./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js	354.8 KiB
./node_modules/.pnpm/react-markdown@8.0.7_@types+react@16.14.66_react@18.3.1/node_modules/react-markdown/lib/react-markdown.js + 88 modules	351.4 KiB
./src/components/ProductComparisonTable/index.tsx + 126 modules	305.8 KiB
./node_modules/.pnpm/cloudinary-core@2.14.0_lodash@4.17.21/node_modules/cloudinary-core/cloudinary-core.js	281.9 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/doll-house.mjs	281.7 KiB
./node_modules/.pnpm/@posthog+brand@0.8.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/director.mjs	275.6 KiB
./src/components/SearchUI/index.tsx + 87 modules	273.7 KiB

---

Eager-graph budgets are report-only until a baseline is established. Sizes are gzip of public/**/*.js; eager size is webpack module source bytes for the modules actually shipped in the entrypoint's initial chunks (post-tree-shake).