--- title: "FirearmCart API" description: "REST API reference for the FirearmCart v1 sales platform API" --- > API Reference Index > Fetch the complete API index at: https://docs.firearmcart.com/api/llms.txt > Use this file to discover all available pages before exploring further. # FirearmCart API The FirearmCart API is a JSON REST API for reading your store's catalog, customers, orders, fulfillments and subscriptions, and for taking payments from your own front end. > **Check your plan first — the API is not included on every plan.** You need > either a plan that includes API & Webhooks access, or the **API & Webhooks > Access** addon on your current plan. Without one, a perfectly valid > token still returns `403` on every request, and your outgoing webhooks will not > fire either. Upgrade or add it from the **Addons** tab on > [Billing](/account/billing#addons); the exact responses are in > [API access gate](/api/authentication#api-access-gate). Every request is authenticated with a bearer token that belongs to **a store, not a person**. Read [Authentication](/api/authentication) before anything else — that one fact changes how you model access in your integration. --- ## Base URL ``` https://api.firearmcart.com/v1 ``` There is no `/api` path segment. The version lives in the path, the host is dedicated to the API, and the API domain is `noindex`ed and returns a redirect to the marketing site at its root. | Property | Value | |----------|-------| | Protocol | HTTPS only | | Format | JSON request and response bodies | | Auth | `Authorization: Bearer ` | | Required header | `Accept: application/json` — see [Errors](/api/errors) | | Default rate limit | 60 requests/minute per store | | Versioning | Path-based (`/v1`). v1 is the only version. | --- ## Get a token 1. Sign in at `https://app.firearmcart.com` and switch to the store you want the token to act on. 2. Go to **Profile → API Tokens** (`/user/api-tokens`). 3. Name the token, tick the abilities it needs, and create it. 4. Copy the token immediately. It is shown once and never again. A token alone is not enough: your plan must include API & Webhooks access, or the store must hold the **API & Webhooks Access** addon. Without one, every request returns `403 forbidden` even with a valid token. Upgrade or add it from the **Addons** tab on [Billing](/account/billing#addons), and see [API access gate](/api/authentication#api-access-gate) for the exact response bodies. --- ## 60-second quickstart Export your token, then list your catalog: ```bash export FIREARMCART_TOKEN="paste-your-token-here" curl https://api.firearmcart.com/v1/products \ -H "Authorization: Bearer $FIREARMCART_TOKEN" \ -H "Accept: application/json" ``` A successful response is a paginated envelope: ```json { "data": [ { "product_id": 1042, "name": "Ruger 10/22 Carbine", "slug": "ruger-10-22-carbine", "price": 32999, "sku": "RUG-1103", "stock_quantity": 12, "in_stock": true, "status": "active", "has_variants": false } ], "links": { "first": "https://api.firearmcart.com/v1/products?page=1", "last": "https://api.firearmcart.com/v1/products?page=4", "prev": null, "next": "https://api.firearmcart.com/v1/products?page=2" }, "meta": { "current_page": 1, "from": 1, "last_page": 4, "path": "https://api.firearmcart.com/v1/products", "per_page": 25, "to": 25, "total": 87 } } ``` > **Note:** `price` above is **32999 cents**. Product and variant prices are integer cents; order and transaction amounts are float dollars. This is the single most common integration bug — read [Conventions](/api/conventions#money-units) before you render a price. --- ## Reference map ### Guides | Page | What it covers | |------|----------------| | [Authentication](/api/authentication) | Bearer tokens, the team-owned token model, all 15 abilities, the API access gate | | [Rate limits](/api/rate-limits) | The 60/min and 30/min buckets, headers, and the 429 response | | [Pagination](/api/pagination) | The `data` / `links` / `meta` envelope, `per_page`, and the two endpoints that don't paginate | | [Errors](/api/errors) | The three error envelopes that actually exist, per status code | | [Conventions](/api/conventions) | The mixed ID scheme and the mixed money units, per resource | | [Webhooks](/api/webhooks) | Consuming outgoing webhooks: payload, verification, retries | ### Endpoints 22 authenticated endpoints across nine resources. | Resource | Endpoints | |----------|-----------| | [Customers & leads](/api/resources/customers) | Create or update a lead, list customers, get a customer | | [Orders](/api/resources/orders) | List orders, get an order, add a post-purchase upsell | | [Subscriptions](/api/resources/subscriptions) | List, get, pause, resume, skip, cancel, update | | [Fulfillments](/api/resources/fulfillments) | List fulfillments, get a fulfillment | | [Products](/api/resources/products) | List products, get a product | | [Payments](/api/resources/payments) | Create a tokenization session, charge a card | | [Shipping, taxation & FFL dealers](/api/resources/shipping-taxation-ffl) | List shipping zones and rates, list tax zones, search the FFL directory | --- ## What the API does not do Being explicit about the gaps saves you a search: - **No catalog writes.** Products, variants, collections, shipping zones and tax zones are read-only over the API. Create and edit them in the dashboard or through a distributor sync. - **No order writes except payments.** You cannot `PATCH` an order, mark it fulfilled, or refund it. Orders are created as a side effect of `POST /v1/payments/charge`, and `POST /v1/orders/{order_id}/upsell` appends to one. - **No webhook management.** Outgoing webhooks are configured in the dashboard only. See [Webhooks](/api/webhooks#there-is-no-webhook-management-api). - **No token management.** Tokens are created and revoked in the dashboard only. - **No customer-facing auth.** There is no shopper login, cart, or checkout session API. Those live on the storefront. --- ## Theme Dev MCP server Separate from the REST API, the same store tokens can drive a Model Context Protocol server for theme development at `https://api.firearmcart.com/mcp/themes`. It speaks JSON-RPC over Streamable HTTP rather than REST, uses the `themes:read` and `themes:write` abilities, and has its own 240/min rate limit. | Page | What it covers | |------|----------------| | [Theme Dev MCP server](/api/mcp) | Endpoint, transport, tokens, abilities, team scoping, connection failures | | [Tools](/api/mcp/tools) | All 33 tools — arguments, results, guardrails, and which ability each needs | | [Resources & prompts](/api/mcp/resources) | The 3 resources and 2 prompts the server hands your agent | --- ## Related documentation - [Webhooks](/integrations/webhooks) — merchant-facing setup and the full event catalogue - [Integrations](/integrations) — prebuilt integrations that may already cover your use case - [Billing](/account/billing) — plans and add-ons, including API & Webhooks access Source: https://docs.firearmcart.com/api/index.mdx