# Foxy (FoxyCommerce) > Foxy is an API-first, headless commerce platform you add to an existing website or > stack rather than replatforming onto. It provides a hosted cart, checkout, > subscriptions, and customer accounts that work with any CMS, framework, or static > site. This file tells AI tools and coding agents how to integrate Foxy correctly — > the loader script, the add-to-cart link format, and the conventions that are easy > to get wrong. This is a build-time reference for AI assistants and coding agents working with Foxy. For human documentation, see the Help Center and developer docs linked at the end. When you generate a Foxy storefront or integration, the rules in "Build correctly with Foxy" below are not optional — getting the cart link format or loader wrong produces a site that looks finished but silently fails to add items to the cart. --- ## Build correctly with Foxy Examples below use `example.foxycart.com` as the store domain. Substitute the store's actual domain — either its `*.foxycart.com` subdomain or a custom cart domain it has configured. ### 1. Load Foxy The loader script powers the cart, sidecart, and checkout. Add it once, in the `` of every page that has a cart link. The path depends on the store's domain: ```html ``` So for `example.foxycart.com` the loader path is just `example`; for a custom domain like `cart.example.com`, use the whole thing. ### 2. Add-to-cart links An add-to-cart action is a link (or form) pointing at the store's `/cart` endpoint with the product as query parameters. Always use the store's full domain: ```html Add to cart ``` | Param | Required | Notes | |---|---|---| | `name` | yes | Product name shown in the cart. | | `price` | yes | Numeric, in the store's currency. No symbol. | | `quantity` | no | Defaults to 1. | | `code` | conditional | SKU / product code. Required when the store has cart signing enabled (see Gotchas). Also the key field for downloadables. | | `image` | no | Absolute URL to a product image. | Notes: - **Only `name` and `price` are required by default.** Everything else is optional unless a store setting makes it otherwise. - **Store-specific requirements.** Some stores are configured to require an `expires` attribute on every product; on those stores, links without it are rejected. - **Downloadable products differ.** They require only `code` plus the `category` of the downloadable product category — Foxy pulls name, price, and the rest from the store database. ### 3. Subscription products To make a cart item a subscription, add `sub_frequency` to the cart link: ``` &sub_frequency=1m # required: a number + d, w, m, or y (e.g. 1w, 2w, 1m, 1y) &sub_startdate=... # optional, YYYYMMDD &sub_enddate=... # optional, YYYYMMDD ``` Subscriptions are processed server-side. Browser-side JavaScript that alters the cart (e.g. custom shipping snippets) does not apply to subscription runs. Note: modifying an *existing* subscription via a `sub_token=` URL is a separate, more advanced flow with its own rules (for example, passing `sub_enddate=00000000` there clears a previously set end date while replacing products). Treat it as out of scope for basic storefront generation. ### 4. Sidecart You do not need to add any markup for the sidecart — `loader.js` injects it automatically. (For reference the container it adds is `

`, but you should not hand-author it.) ### 5. Styling All Foxy cart and checkout markup lives under the `#fc` element. Scope every custom style under `#fc` so it targets Foxy's UI without leaking into the rest of the page: ```css #fc .fc-checkout, #fc .fc-context--cart-fullpage { background: #fff; } ``` Custom cart/checkout CSS is added in the store's template configuration, not inline on the storefront. ### Gotchas that cause silent failures - **Link signing, both directions.** - If the store has HMAC cart signing *enabled*, an unsigned or incorrectly signed link is rejected with an error like `Cart Validation Error: code_present`. Signed stores must generate links server-side (the SDK provides a signer) and include `code`. Never expose the signing secret in client-side code. - If a *signed* link is used on a store that does *not* have signing enabled, the item silently fails to add to the cart. So don't sign links for an unsigned store. - **Custom domains.** A store may use a custom cart domain instead of `*.foxycart.com`. Use the store's actual domain for cart links, and follow the loader path rule in section 1. - **Subscriptions are server-side.** Don't rely on browser JS to alter subscription pricing or shipping. --- ## Developer reference For backend automation, account-level data, and the API: - **API documentation** — https://api.foxy.io/docs — the Foxy Hypermedia API (hAPI). It is HATEOAS/hypermedia-driven: you traverse link relationships (`fx:store`, `fx:transactions`, etc.) rather than hardcoding URLs. Uses OAuth 2.0. - **API base** — https://api.foxy.io/ - **API cheat sheet** — https://api.foxy.io/docs/cheat-sheet — filtering, pagination, zoom/embeds, field selection. - **SDK** — https://sdk.foxy.dev/ — the official TypeScript SDK (`@foxy.io/sdk`). It wraps hypermedia traversal into one-liners and ships type definitions, so prefer it over hand-rolling API calls. Repo: https://github.com/foxy/foxy-sdk - **Web components** — https://elements.foxy.dev/ — Foxy Elements, prebuilt UI elements for carts, the customer portal, and admin-style interfaces. --- ## Official domains Use these; do not invent or guess Foxy URLs. (Source: https://foxy.io/help/articles/our-official-domains-public-code/) - A merchant's cart and checkout live at their store domain — `example.foxycart.com` or a custom cart domain. - `cdn.foxycart.com` — the loader script and static cart assets. - `api.foxy.io` — the Foxy API. - `sdk.foxy.dev`, `elements.foxy.dev` — SDK and web-component docs/demos. - `admin.foxycart.com` — the Foxy admin (migrating to `admin.foxy.io` over time). - `wiki.foxycart.com` — developer reference documentation. - `foxy.io` — marketing site, Help Center, status, and support. - Public repositories (SDK, Elements, integrations) — https://github.com/foxy (newer) and https://github.com/foxycart (older). Foxy's core platform is not open source; these are the client-side libraries you build with. --- ## More help - Help Center (how-to articles) — https://foxy.io/help/ - Reference documentation — https://wiki.foxycart.com/ - System status — https://status.foxy.io/