GitHub - lsb11/shopify-capi-validator: Validate Meta CAPI & TikTok Events API payloads locally before they fail silently. Zero deps, MIT. · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
lsb11
shopify-capi-validator
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>1 Commit<br>1 Commit
bin
bin
lib
lib
test
test
.gitignore
.gitignore
LICENSE
LICENSE
README.md
README.md
package.json
package.json
View all files
Repository files navigation
shopify-capi-validator
Validate Meta Conversions API (CAPI) and TikTok Events API payloads locally — before you go live.
Meta and TikTok have one infuriating behaviour in common: they do not tell you when a payload is wrong. Send a raw (un-hashed) email, a millisecond timestamp, or a Purchase with no currency, and the event is simply never matched — no error, no warning, just silently missing conversions and a tanking Event Match Quality score. You find out hours later in Events Manager, if at all.
This is a zero-dependency CLI that catches those failures in one command.
npx shopify-capi-validator --payload ./webhook.json
Platform: META Events: 1<br>✓ event_name present (Purchase)<br>✗ event_time looks like milliseconds<br>→ Meta expects SECONDS (10 digits), not milliseconds (13). Divide by 1000.<br>✓ event_id present (enables Pixel deduplication)<br>✗ user_data.em is RAW email (contains "@")<br>→ PII must be SHA-256 hashed. Lowercase + trim, THEN hash. Raw values fail matching silently.<br>✓ user_data.client_ip_address sent raw (correct)<br>✗ custom_data.currency missing for Purchase<br>→ Required. ISO 4217, e.g. "USD", "GBP". Meta rejects Purchase without currency.
Summary 3 passed 1 warnings 3 failed
Exit code is 1 when any check fails, so it drops straight into CI.
Install
No install needed — run it with npx. Or add it to a project:
npm install --save-dev shopify-capi-validator
Usage
# from a file<br>npx shopify-capi-validator --payload ./event.json
# pipe from anywhere (curl, jq, a log line)<br>cat event.json | npx shopify-capi-validator
# force a platform instead of auto-detecting<br>npx shopify-capi-validator -p event.json --platform tiktok
# machine-readable output for scripts / CI<br>npx shopify-capi-validator -p event.json --json
Flag<br>Description
-p, --payload<br>Path to a JSON payload (or pipe via stdin)
--platform<br>meta | tiktok | auto (default: auto-detect)
--json<br>Output machine-readable JSON
--quiet<br>Only show failures + summary
-h, --help<br>Help
What it checks
Meta Conversions API
event_name, event_time, event_id, action_source present
event_time is Unix seconds (catches the classic milliseconds mistake) and inside the 7-day window
event_id present — required so the Pixel and CAPI events deduplicate instead of double-counting
user_data has at least one strong identifier (em, ph, fbc, or external_id)
PII fields (em, ph, fn, ln, ct, st, zp, country, external_id) are SHA-256 hashed (64-char hex) — not raw
Fields that must stay raw (client_ip_address, client_user_agent, fbc, fbp) are not accidentally hashed
fbc / fbp use the fb.1.. format
Purchase events include a numeric value and ISO-4217 currency
TikTok Events API
event, event_time, event_id present
user has at least one identifier (email, phone, ttclid, external_id)
PII SHA-256 hashed; ip / user_agent left raw
CompletePayment includes value + currency
Use it as a library
const { validatePayload } = require('shopify-capi-validator');
const result = validatePayload(myPayload, { platform: 'meta' });<br>// → { platform, events: [{ findings: [{ level, msg, hint }] }] }
Why hashing is the #1 issue
A SHA-256 digest is always 64 hexadecimal characters. If a field that Meta<br>expects hashed doesn't look like that, this tool flags it. Meta's own guidance<br>is explicit: PII must be lowercased, trimmed, then SHA-256 hashed — and the<br>platform will not warn you if you skip it.
If you're setting up server-side tracking on Shopify and want the full<br>field-by-field mapping and a free Make.com implementation, there's a...