The FirearmCart API is a JSON REST API for reading your store’s catalog, customers, orders, fulfillments and subscriptions, for publishing blog articles, 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 AI & API access, or the AI & API Access addon on your current plan. Without one, a perfectly valid token still returns
403on every request. Outgoing webhooks are the exception: they’re included on every plan. Upgrade or add the addon from the Addons tab on Billing; the exact responses are in API access gate.
Every request is authenticated with a bearer token that belongs to a store, not a person. Read Authentication before anything else — that one fact changes how you model access in your integration.
Base URL
https://api.firearmcart.com/v1There is no /api path segment. The version lives in the path, the host is dedicated to the API, and the API domain is noindexed 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 <token> |
| Required header | Accept: application/json — see Errors |
| Default rate limit | 60 requests/minute per store |
| Versioning | Path-based (/v1). v1 is the only version. |
Get a token
- Sign in at
https://app.firearmcart.comand switch to the store you want the token to act on. - Go to Profile → API Tokens (
/user/api-tokens). - Name the token, tick the abilities it needs, and create it.
- Copy the token immediately. It is shown once and never again.
A token alone is not enough: your plan must include AI & API access, or the store must hold the AI & API Access addon. Without one, every request returns 403 forbidden even with a valid token. Upgrade or add it from the Addons tab on Billing, and see API access gate for the exact response bodies.
60-second quickstart
Export your token, then list your catalog:
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:
{
"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:
priceabove 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 before you render a price.
Reference map
Guides
| Page | What it covers |
|---|---|
| Authentication | Bearer tokens, the team-owned token model, all 25 abilities, the API access gate |
| Rate limits | The 60/min and 30/min buckets, headers, and the 429 response |
| Pagination | The data / links / meta envelope, per_page, and the three endpoints that don’t paginate |
| Errors | The three error envelopes that actually exist, per status code |
| Conventions | The mixed ID scheme and the mixed money units, per resource |
| Webhooks | Consuming outgoing webhooks: payload, verification, retries |
Endpoints
31 authenticated endpoints across eleven resources.
| Resource | Endpoints |
|---|---|
| Customers & leads | Create or update a lead, list customers, get a customer |
| Orders | List orders, get an order, add a post-purchase upsell, calculate an upsell’s tax |
| Subscriptions | List, get, pause, resume, skip, cancel, update |
| Fulfillments | List fulfillments, get a fulfillment |
| Products | List products, get a product |
| Blogs & articles | List and create blogs; list, get, create and update articles; take an SEO tool’s publishing webhook |
| Payments | Create a tokenization session, charge a card |
| Shipping, taxation & FFL dealers | List shipping zones and rates, list tax zones, calculate an order’s tax, 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
PATCHan order, mark it fulfilled, or refund it. Orders are created as a side effect ofPOST /v1/payments/charge, andPOST /v1/orders/{order_id}/upsellappends to one. - No webhook management. Outgoing webhooks are configured in the dashboard only. See Webhooks.
- 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.
MCP server
Separate from the REST API, one Model Context Protocol server at https://api.firearmcart.com/mcp lets AI apps and agents work with a store and its storefront themes. Claude, ChatGPT, Grok and Muse connect by signing in with OAuth; header-based clients use the same store API tokens as the REST API. It speaks JSON-RPC over Streamable HTTP rather than REST and has its own 240/min rate limit.
| Page | What it covers |
|---|---|
| MCP server | Connecting with OAuth or an API token, permissions, how changes are confirmed, limits, errors |
| Tools | All 84 tools — arguments, results, guardrails, and which ability each needs |
| Resources & prompts | The 3 resources and 2 prompts the server hands your agent |
Related documentation
- Webhooks — merchant-facing setup and the full event catalogue
- Integrations — prebuilt integrations that may already cover your use case
- Billing — plans and add-ons, including AI & API access

