API access is not included on every plan. Before you build against it, check your store has it: either upgrade to a plan that includes AI & API access, or add the AI & API Access addon from the Addons tab on Billing. Without one, a valid token still gets
403on every/v1request — see API access gate below.
Every v1 request carries a personal access token in an Authorization header:
curl https://api.firearmcart.com/v1/orders \
-H "Authorization: Bearer $FIREARMCART_TOKEN" \
-H "Accept: application/json"The REST API has no OAuth flow, no API key/secret pair, no request signing, and no session cookie. The bearer token is the entire credential.
AI apps (Claude, ChatGPT, Grok, Muse) connecting to the MCP server sign in with OAuth instead of using a token. Those sign-ins only reach the MCP server, never /v1.
Creating a token
- Sign in to
https://app.firearmcart.comas the store’s owner or an admin. Team members without the admin role can’t open the API Tokens page. - Switch to the store you want the token to act on. The token is bound to whichever store is current when you create it, and this cannot be changed afterwards.
- Open Profile → API Tokens (
/user/api-tokens). - Enter a name, tick the abilities you need, and create.
Six read abilities (customers:read, orders:read, fulfillments:read, products:read, shipping:read, taxation:read) are pre-ticked as a read-only default. At least one ability must be selected — a token with no abilities cannot be created.
Token lifetime
Tokens do not expire. There is no configured expiry and no refresh flow. A token is valid until you delete it in the dashboard, which takes effect immediately.
Store tokens like passwords. A leaked token grants everything its abilities allow, for as long as it exists.
Abilities
Each route is guarded by exactly one ability. A token missing that ability gets 403 even if the token is otherwise valid and the store has API access.
| Ability | Grants | Endpoints |
|---|---|---|
customers:read |
Read customer records and their addresses | GET /v1/customers, GET /v1/customers/{customer_id} |
customers:write |
Create or update a customer by email | POST /v1/leads |
orders:read |
Read orders, line items, transactions, addresses | GET /v1/orders, GET /v1/orders/{order_id} |
orders:write |
Record tracking, send orders to their suppliers, change who ships a line, order notes and the receiving FFL over MCP | MCP server only — no v1 REST route |
orders:upsell |
Charge an add-on onto an existing paid order, and calculate its tax first | POST /v1/orders/{order_id}/upsell, POST /v1/orders/{order_id}/upsell/tax |
fulfillments:read |
Read fulfillments and their shipments | GET /v1/fulfillments, GET /v1/fulfillments/{fulfillment_id} |
products:read |
Read the catalog, variants and media | GET /v1/products, GET /v1/products/{product_id} |
shipping:read |
Read shipping zones and their rates | GET /v1/shipping |
taxation:read |
Read manual tax zones, and calculate the tax on an order before charging it | GET /v1/taxation, POST /v1/taxation/calculate |
payments:tokenize |
Open a hosted card-entry session | POST /v1/payments/tokenize |
payments:charge |
Charge a card and create an order | POST /v1/payments/charge |
subscriptions:read |
Read Reload subscriptions | GET /v1/subscriptions, GET /v1/subscriptions/{uuid} |
subscriptions:write |
Pause, resume, skip, cancel, or edit a subscription | POST /v1/subscriptions/{uuid}/pause, /resume, /skip, /cancel, PATCH /v1/subscriptions/{uuid} |
ffl:read |
Search the FFL dealer directory | GET /v1/ffl-dealers |
settings:read |
Read store settings, payment gateways (read-only), domains, setup progress, and shipping and tax zones over MCP | MCP server only — no v1 REST route |
settings:write |
Change store details, branding and FFL visibility, set the store FFL from a license copy, connect domains, and save shipping and tax zones over MCP | MCP server only — no v1 REST route |
themes:read |
Read theme files over MCP | MCP server only — no v1 REST route |
themes:write |
Write theme files over MCP | MCP server only — no v1 REST route |
products:write |
Edit products (prices, publish status, descriptions, specifications, SEO) and collections over MCP | MCP server only — no v1 REST route |
inventory:write |
Change the store’s own stock over MCP | MCP server only — no v1 REST route |
discounts:read |
Read discount codes over MCP | MCP server only — no v1 REST route |
discounts:write |
Create and update discount codes over MCP | MCP server only — no v1 REST route |
analytics:read |
Read sales and traffic summaries over MCP | MCP server only — no v1 REST route |
blogs:read |
Read the store’s blogs and blog articles | GET /v1/blogs, GET /v1/articles, GET /v1/articles/{article_id} |
blogs:write |
Create blogs, and create or update articles, including from an SEO tool’s publishing webhook | POST /v1/blogs, POST /v1/articles, PATCH /v1/articles/{article_id}, POST /v1/articles/webhook |
Twenty-five abilities in total. Ten of them do not unlock any /v1 endpoint: themes:read, themes:write, products:write, inventory:write, orders:write, discounts:read, discounts:write, analytics:read, settings:read and settings:write are used only by the MCP server at https://api.firearmcart.com/mcp. The read abilities for customers, orders, products, subscriptions and FFL dealers work on both. blogs:read and blogs:write work on /v1 only: the MCP server’s blog tools use themes:read and themes:write.
The MCP server accepts a token holding any of its abilities and then lists only the tools that token may use: a token holding only themes:read sees the theme read tools, not the theme write tools or the store tools. A token holding nothing but blog abilities is refused there. See Permissions for which ability shows which tools and Tools for the full surface. The MCP server also has its own rate limit; see Rate limits.
Choosing abilities
Grant the narrowest set that works. Two are worth extra thought:
payments:chargelets the token move money. Anything holding it can create orders and charge stored cards.orders:upselldoes the same on an existing order, and is also the only endpoint that requires you to supply an idempotency key.
A token holding either of those, or payments:tokenize, is refused by the MCP server. Give AI apps their own token without them.
API access gate
Passing the token check is not enough. Every /v1 request also runs an access gate that checks the store’s plan and billing standing, and it can reject you with three distinct responses.
| Status | Body | Meaning |
|---|---|---|
401 |
{"error": "unauthorized", "message": "Invalid API token."} |
The credential authenticated, but did not resolve to a store. Practically: the request reached the API as something other than a store token. |
403 |
{"error": "forbidden", "message": "API access is not enabled for this team."} |
The store’s plan does not include AI & API access, and it holds no AI & API Access add-on. |
403 |
{"error": "subscription_expired", "message": "Your subscription has expired. Please renew to continue using the API."} |
The store’s subscription is suspended after a failed payment, or is past its cancellation date. |
A store passes the gate if any of the following is true: it is a demo account, it has API access granted directly by an administrator, its plan includes API access, or it holds an active API access add-on.
A token that FirearmCart staff created to work on your store, such as on your theme, is marked Staff on the API Tokens page. It passes the gate whatever your plan. Delete it there when the work is done.
Note: Outgoing webhooks don’t go through this gate: they’re included on every plan. See Webhooks.
Note that this gate is distinct from an invalid or deleted token. A revoked, mistyped or missing token fails earlier, at the authentication guard, and produces {"message": "Unauthenticated."} — see Errors.
Always send Accept: application/json
Successful responses are JSON regardless of headers, but error responses are not. Without Accept: application/json:
- A
401becomes a302redirect to the dashboard login page. - A
422validation failure becomes a302redirect rather than a JSON error body. - Other failures render an HTML error page.
Send the header on every request, including GETs. The one exception is POST /v1/articles/webhook, which answers in JSON whatever the request asks for, because the SEO tools that call it don’t send the header.
Revoking a token
Delete the token at Profile → API Tokens. Revocation is immediate — the next request with that token fails authentication with 401 Unauthenticated. There is no revocation endpoint; see What the API does not do.
If you suspect a leak, delete the token first and issue a replacement second. There is no way to rotate a secret in place.
Related documentation
- MCP server — connecting Claude, ChatGPT, Grok and other MCP clients with OAuth or a token
- Rate limits — per-store request budgets
- Errors — every failure shape, per status code
- Team members — who can reach the dashboard page that mints tokens
- Billing — plans and add-ons that satisfy the API access gate

