Foxy (foxy.io, formerly FoxyCart) is a hosted cart/checkout layer: your site keeps the product pages, Foxy hosts the cart, checkout, and receipt. Products live in add-to-cart links/forms secured by HMAC signing; automation runs through a hypermedia REST API (hAPI, OAuth 2.0) and HMAC-signed webhooks with real retry semantics. The go-to when a Webflow/builder site outgrows native ecommerce.
Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated platform knowledge.
Ask only what you can't infer from the user's prompt:
-
What are you trying to do?
- A) Add Foxy to a site (Webflow/WordPress/Squarespace/Wix/Framer/custom)
- B) Secure products — HMAC-sign add-to-cart links/forms
- C) Integrate transactions/subscriptions with a CRM/fulfillment (hAPI, webhooks)
- D) Style the cart/checkout to match the site (template sets)
- E) Understand pricing (plan + 1% capped per-transaction fee)
-
Do you have a build step or serverless functions? Link signing needs one (SDK signer at build time, or a deployed signer function).
Skip-ahead rule: if the user's prompt already has enough context, go straight to Step 2.
Step 2 — Route or answer directly
| If the user's question is about… | Route to |
|---|---|
| Which cart/checkout platform to pick (Foxy vs Snipcart/Ecwid/Shopify Buy Button) | /sales-checkout {question} |
| JAMstack carts with crawler validation (Snipcart) | /sales-snipcart {question} |
| Widget-store platforms (Ecwid) | /sales-ecwid {question} |
| Checkout-conversion strategy across tools | /sales-checkout {question} |
| Subscription billing strategy / migrating subscribers | /sales-subscription-billing {question} |
| Tax / Merchant-of-Record obligations | /sales-merchant-of-record {question} |
When routing, give the exact command: "This is a {domain} question — run: /sales-checkout {original question}"
Otherwise, answer Foxy-specific questions directly using Step 3.
Step 3 — Foxy platform reference
Read references/platform-guide.md for the full reference — capabilities & automation surface, pricing, data model, and quick-start recipes (HMAC webhook verification, build-time link signing, hAPI transaction pulls).
For raw hAPI detail, webhook events/headers/retry semantics, and the signing model, read references/foxy-api-reference.md.
Answer using only the relevant section — don't dump the full reference.
Step 4 — Actionable guidance
- Treat HMAC link/form signing as mandatory, not optional — unsigned add-to-cart links let buyers edit
price=in the URL. Sign at build time with the official SDK (@foxy.io/sdkSigner) or deploy a pre-built serverless signer; never put the store secret in the browser. When explaining the model, note it works on fully static/CDN pages with nothing to crawl — the alternative to Snipcart's crawler validation, which needs server-fetchable product URLs. - Verify webhooks by HMAC-SHA256 of the RAW body (hex digest, webhook encryption key, constant-time compare against
Foxy-Webhook-Signature) — and reply 200 within a minute. - Watch for webhook auto-deactivation: Foxy retries 11 more times over an hour, then deactivates the webhook after 12 consecutive failures — monitor deactivation and replay missed events with admin refeed (
Foxy-Webhook-Refeed: true). - Code against hAPI link relations, not hardcoded URLs — it's a HATEOAS API; follow
fx:transactions/fx:subscriptionslinks and usezoomto embed related data; let the SDK handle OAuth token refresh. - Style Foxy's templates to match the host site — cart/checkout/receipt are Foxy-hosted and will look mismatched out of the box (the top Webflow-user complaint); budget template work and expect to run two dashboards.
- Quote pricing as plan fee + 1% per transaction (min 5¢, capped ~7.5–35¢ by plan) plus gateway fees, flagged best-effort — point the user to foxy.io/pricing; the caps make Foxy cheaper than uncapped 2% carts at higher basket sizes.
If you discover a gotcha or tip not in references/learnings.md, append it there with today's date.
Gotchas
Best-effort from research (2026-07) — review these, especially pricing tiers (sources conflict) and the beta admin UI status.
- Unsigned links = editable prices. HMAC product verification is the security model; a prototype without it ships a price-tampering hole.
- 12 consecutive webhook failures silently deactivate the webhook — a flaky endpoint doesn't just miss events, it turns the firehose off. Alert on deactivation; refeed to recover.
- The admin UI is dated ("circa 2008" per reviews) with a new dashboard in beta — and Foxy is a second dashboard next to your site builder's; factor the ops overhead.
- Cart/checkout/receipt are Foxy-hosted pages styled via template sets — they don't inherit your site's design; unstyled they read as a different product mid-purchase.
- Deep customization, thin guidance — reviewers report feeling "lost in the woods" among options; start from the Webflow/builder getting-started guides and change one template at a time.
- Not a Merchant of Record — you own tax obligations; gateway fees are additional to Foxy's fee.
Related skills
/sales-checkout— Cart/checkout platform selection (Foxy vs Snipcart vs Ecwid vs Shopify Buy Button) and conversion strategy/sales-snipcart— Snipcart platform help (the crawler-validation alternative for JAMstack markup-defined products)/sales-ecwid— Ecwid platform help (the widget-store alternative with a hosted storefront UI)/sales-subscription-billing— Recurring billing strategy and subscriber migration across platforms/sales-merchant-of-record— Tax/VAT handling (Foxy is not a Merchant of Record)/sales-do— Not sure which skill to use? The router matches any sales objective to the right skill. Install:npx skills add sales-skills/sales --skill sales-do -a claude-code
Examples
Example 1: Lock down add-to-cart links (developer/automation)
User says: "I realized customers can change the price in my Foxy add-to-cart URL before checkout. How do I stop that?"
Skill does: Explains HMAC product verification — every product parameter gets signed with the store secret so the cart rejects tampered values — and applies Recipe 2: sign links/forms at build time with @foxy.io/sdk's Signer (or deploy Foxy's pre-built serverless signer for no-build sites), keeping the secret server-side.
Result: Tampered links are rejected at the cart; prices are enforceable again.
Example 2: Webhook-driven fulfillment that survives failures
User says: "Sync every completed Foxy order into our warehouse — and last month our webhook just stopped firing."
Skill does: Sets up the transaction/created JSON webhook, verifies Foxy-Webhook-Signature (HMAC-SHA256 hex of the raw body, constant-time compare), returns 200 fast — then explains the stoppage: 12 consecutive failures auto-deactivate the webhook. Adds deactivation monitoring, admin refeed for the gap, and an hAPI reconciliation pull.
Result: Verified, monitored order sync with a documented recovery path.
Example 3: Webflow store outgrowing native ecommerce
User says: "Webflow Ecommerce only gives me Stripe and PayPal and no real subscriptions — is Foxy the answer?"
Skill does: Maps the fit — Foxy adds 100+ gateways, any-frequency subscriptions, donations, and configurable products on top of the existing Webflow site — while flagging the trade-offs from reviews (separately-styled checkout needing template work, a dated second dashboard, learning curve) and the pricing shape (plan + 1% capped per transaction, best-effort — verify at foxy.io/pricing). Routes a broader platform comparison to /sales-checkout.
Result: User decides with the real trade-offs, not just the feature list.
Troubleshooting
Webhook stopped delivering entirely
Symptom: Events flowed for months, then nothing.
Cause: The endpoint failed 12 consecutive deliveries (non-200 or >1-minute responses) and Foxy auto-deactivated the webhook.
Solution: Fix the endpoint (fast 200, verify against the raw body), re-enable the webhook, and replay the gap via admin refeed — refeeds arrive with Foxy-Webhook-Refeed: true. Add monitoring so deactivation pages you.
Signature verification fails on every webhook
Symptom: Computed HMAC never matches Foxy-Webhook-Signature.
Cause: Hashing a re-serialized/parsed body instead of the raw bytes, using the wrong key (it's the webhook's encryption key, not an API token), or comparing against a base64 digest when Foxy sends hex.
Solution: HMAC-SHA256 the raw request body with the webhook encryption key, hex-encode, hmac.compare_digest — Recipe 1 in the platform guide.
Checkout looks nothing like my site
Symptom: Buyers hit a cart/checkout that visually breaks from the Webflow design. Cause: Cart, checkout, and receipt are Foxy-hosted pages with their own template sets — they don't inherit the host site's styles. Solution: Customize the template sets (colors, fonts, layout) to match the site; start from Foxy's builder-specific guides and iterate one template at a time. Budget this styling work into any Foxy adoption estimate.