Developer guide
RollStamp API covers the compliance book, the Maker Console, source catalogs and order routing, and dealer vetting. One key opens the routes for the account. Most routes answer with JSON; the file exports return the format they name.
Getting started
Send requests to /v1/... with the key in x-api-key. A successful call returns data; a failed call returns an error code and a readable message.
{ "success": true, "data": { ... } }
{ "success": false, "error": { "code": "invalid_parameter", "message": "...", "details": ... } }
Branch on error.code. The message can change; the code does not. Check the key first:
curl https://api.rollstamp.example/v1/ping -H 'x-api-key: fflsbx_std_9f3k2m7q4t'
The API tester sends a request from the browser. openapi.json is the field-level schema, and llms.txt is a short route map for coding agents.
Keys, IPs and limits
A key can read records and make writes. Keep it on a server. A browser or mobile app should call your server, not hold the key. Each key also has an IP allowlist, so a request is checked twice: a valid key, from an allowed address.
Send x-api-key: <key> or Authorization: Bearer <key>. A missing key returns 401; an address outside the allowlist returns 403. Repeated bad keys from one address can return 429.
| Tier | Requests per minute | Requests per day |
|---|---|---|
| standard | 60 | 10,000 |
| pro | 300 | 100,000 |
| enterprise | 1000 | 1,000,000 |
A successful request made with an account key carries X-RateLimit-Limit and X-RateLimit-Remaining. A 429 carries Retry-After; wait that long before retrying. GET /v1/usage shows today's calls by endpoint.
Sample keys
| Key | Account | Tier | Allowed IPs | What it shows |
|---|---|---|---|---|
fflsbx_std_9f3k2m7q4t | Demo Storefront | standard | 127.0.0.1 ::1 | Ready to go: four validated distributors, store pickup configured. |
fflsbx_pro_4h8w1z6c2r | New Integration | pro | 127.0.0.1 ::1 203.0.113.25 | Fresh account with no distributors: walk through setup. |
fflsbx_ent_7x2n5b8v1k | Enterprise Partner | enterprise | 198.51.100.7 | Only allowed from 198.51.100.7, so calls from 127.0.0.1 get ip_not_allowed. |
fflsbx_new_3c6y9u2p5e | Pending Enrollment | standard | none | No registered server IPs yet, so every call gets ip_whitelist_required. |
Compliance book
Each license has its own book. Create a license with POST /v1/compliance/licenses; the license number determines the type. Every acquisition, disposition, hold and correction stores recorded_by. Every correction keeps the earlier version.
POST /v1/compliance/acquisitions:RECEIVE,MANUFACTURE(Type 07 or 10),IMPORT(Type 08 or 11) orFOUND.POST /v1/compliance/dispositions: an FFL transfer, retail 4473, exempt transfer, return to source, theft or loss, destruction, or NFA Form 3, 4 or 5. A type that can be held acceptspending: true; commit or cancel it through the disposition routes.POST /v1/compliance/assembleand/disassemble: move between a receiver and a finished firearm.GET /v1/compliance/items,GET /v1/compliance/book,GET /v1/compliance/exceptions.POST /v1/compliance/items/{id}/corrections: add a version with a reason.GET /v1/compliance/syncandPOST /v1/compliance/sync/{id}/ack: the FastBound queue.
The FastBound adapter in api/src/integrations/fastbound drains that queue and acknowledges each entry. It is off unless the FastBound account number, FastBound API key, FastBound audit user and a RollStamp API key are set. No live FastBound account is connected in this build.
POST /v1/compliance/acquisitions
{ "license_id": "lic_...", "type": "RECEIVE", "recorded_by": "[email protected]",
"item": { "type": "PISTOL", "manufacturer": "Example Arms", "model": "Stamp", "serial": "EX-000418", "caliber": "9mm" } }
A second open line for the same manufacturer and serial on one license is refused. A disposition can carry form4473_ref, nfa_form_ref and the NICS status; the book stores what you send. A retail 4473 needs a form4473_ref. Form 3 and Form 5 each need an nfa_form_ref. A Form 4 needs both a form4473_ref and an nfa_form_ref.
Recording rules and deadlines come from a data table with a citation. A citation marked (verify) is waiting on a legal review. Do not treat a guide value as legal advice. FastBound remains the legal system of record by default; switching a license to RollStamp needs a recorded counsel sign-off and no FastBound change still waiting to sync.
Maker Console
Serial series are for Type 07 and Type 10 manufacturers. A product template describes the firearm and names an excise category; it can carry an importer when one applies. A series needs a width. A prefix, the current-year segment and a suffix are optional, and the series issues values in order.
POST /v1/manufacturing/templatesandPOST /v1/manufacturing/series.GET /v1/manufacturing/series/{id}/next: preview the next value.POST /v1/manufacturing/series/{id}/reservations: reserve up to 1,000 values.POST /v1/manufacturing/scans: mark a reserved serial from a scan. A refused scan is logged.POST /v1/manufacturing/builds: complete a build into the book.GET /v1/manufacturing/laser-jobs/export.csvor.txt: a laser export file.POST /v1/manufacturing/excise/sales,GET .../count,GET .../worksheet.
A new reservation skips any value that already has a serial record or an open book line, up to 10,000 skipped values in one request. Past that it returns reservation_skip_limit instead of guessing. A completed build calls the book with a MANUFACTURE acquisition and moves the serial from marked to acquired. If the book refuses, the serial stays marked and no build is created.
The excise worksheet groups rows by category and shows units, gross receipts, tax and the citation behind each line, plus the year-to-date manufactured count. Rates, the small-manufacturer threshold and quarterly due dates sit in a data table whose citations are marked (verify). The worksheet is not a filed return.
Sources and configuration
The account keeps one configuration document: active sources, credentials, pricing, product restrictions and pickup settings. Read it, edit it, write it back whole.
GET /v1/distributorslists each source, itsconfig_schemaand adefault_config.GET /v1/config, edit, thenPUT /v1/config. The PUT replaces the whole document, so start from a fresh read. Masked secrets read as********; send them back unchanged to keep them.POST /v1/config/validatewith an empty body checks the saved credentials. A product route only serves a validated source. Send a configuration in the body for a dry run that saves nothing.
PUT /v1/config?validate=true
{ "configuration": { "distributors": { "Lipseys": { "active": true, ... } }, ... } }
A schema failure returns 400 schema_validation_failed with {path, message} for every problem. With ?validate=true, a save that would remove more of the live catalog than the account threshold is refused with 409 validation_failed before anything changes. The setup page in the tester performs the same three steps with a form.
Catalog
The catalog holds every offer from an active, validated source after your restrictions and pricing. unit_price is your cost; retail_price follows your markup; with respect_map on, it does not go below MAP.
GET /v1/products/search: up to 100 rows per page, depth-capped at 10,000, with filters for text, UPC, source, manufacturer, class, category, price and stock.GET /v1/products/{upc}: every offer for one UPC.GET /v1/products/{upc}/history: three months of stock and cost changes.GET /v1/products/facets: manufacturers, categories and classes for filters.GET /v1/products/catalog: the whole catalog as a snappy parquet file behind a presigned URL. Keepexport_versionand send it aslast_version; an unchanged catalog answerschanged: falseand does not use the download window. A new export is allowed once every 20 minutes.
GET /v1/products/search?q=9mm&in_stock=true&sort=price&page_size=10
GET /v1/products/643740108515
GET /v1/products/catalog?last_version=v=20261117T130000-...
Analytics
Reports are built from daily stock and price movement across sources: top-products, on-sale, margin-opportunities, trending, new-arrivals, newly-available, price-gaps. Each takes window (7d, 30d, 60d, 90d), limit (up to 200), product_class and category_id.
GET /v1/analytics/trending?window=30d&product_class=FA&limit=20
Dealer directory
GET /v1/ffls?zip=37201&radius=25 requires a 5-digit ZIP; name is optional. It returns up to 150 dealers, best first: a license already on file in the exact ZIP, then an on-file nearby license, then an exact ZIP with no file, then the rest. GET /v1/ffls/{license_number} reads one dealer; an X in the license matches any character. For a dealer used by one of your own orders, the license and SOT copies are at /v1/ffls/{license_number}/documents/ffl and /v1/ffls/{license_number}/documents/sot when the document is on file.
Restrictions
POST /v1/restrictions/check tests 1 to 100 items against the account rule list: states, counties, cities and ZIPs against UPCs, SKUs, classes, categories and attributes such as magazine capacity. For a US destination, shipping.state is required. The result returns approved, the blocking rules, the warnings and the manual review matches. Each hit carries a message you can show a customer.
POST /v1/restrictions/check
{ "shipping": { "state": "CA", "zip": "94105" }, "items": [ { "upc": "760310155875" }, { "product_class": "AO" } ] }
Quotes and orders
POST /v1/orders/quote finds the cheapest in-stock source for each item, counting estimated shipping unless the account ignores it, and returns up to five alternatives. POST /v1/orders places the order.
order_idis yours and is the idempotency key. A repeat returns409 duplicate_order. Do not retry with a new id.sourcing_modedefaults to"exact", which uses the source and SKU you name or returnssourcing_unavailable."optimal"picks by cost.- A firearm ships to the dealer in
ffl.licenseNumber. Other items can drop-ship to the customer when the source allows it. ship_to_store: truesends the order to the pickup address in the configuration.- An account may place at most 60 orders an hour and 500 a day.
POST /v1/orders
{ "order_id": 10021,
"customer": { "name": "Jane Sample", "email": "[email protected]", "address1": "1 Main St", "city": "Nashville", "state": "TN", "zip": "37201" },
"items": [ { "distid": "LIP", "distsku": "LP108515", "upc": "643740108515", "qty": 1, "ffl_req": true } ],
"ffl": { "licenseNumber": "4-37-201-01-8K-70207" } }
Tracking
An order starts as submitted, submitted_by_email or sent_to_vendor, moves to processing, then to shipped. The shipment moves from awaiting_shipment to in_transit to delivered, with a carrier and tracking number. Read one order with GET /v1/orders/{order_id}, page through GET /v1/orders, or search GET /v1/fulfillment/history by PO number, distributor order number or tracking number. Failed placements appear under errors.
Fraud reports
POST /v1/fraud/check takes an address, email or phone. A match means hold for review, not cancel. An address matches addresses, an email matches emails and a phone matches phones; a shipping address does not count when the order ships to an FFL. A name, IP address or item overlap only adds weight. You see counts and dates, never another dealer's raw record. Report a confirmed fraud with POST /v1/fraud/reports; a destination marked as an FFL cannot be reported. Remove your own report with DELETE /v1/fraud/reports.
POST /v1/fraud/check
{ "shipping_address_1": "123 Main St Apt 4", "shipping_postcode": "30301", "email": "[email protected]" }
Routing and carrier rates
GET /v1/orders/{order_id}/routing shows, for each line of an order, the source that was chosen, the rule that chose it (exact_source, lowest_landed_cost or lowest_cost_consolidated), a sentence explaining it, and a candidate list with stock and landed cost. GET /v1/inventory/{sku} takes a UPC or a source SKU and lists stock and cost at each source that carries it, cheapest first.
POST /v1/shipping/rates compares carrier services for one parcel. Add "carrier_rates": true and "destination_zip" to a quote to get the same comparison for each order in the plan.
POST /v1/shipping/rates
{ "origin_zip": "37201", "destination_zip": "98101", "weight_lb": 4, "contents": "handgun" }
Rates come from sample tables (zone by distance, price by billable weight), with an estimated weight and a sample warehouse ZIP when quoting. Live carrier accounts are not connected. Services that cannot carry the contents are listed under excluded with the reason.
Vetting checks
A check verifies a dealer license (ffl_dealer), an order's destination against the licensed premise (ship_to) or a vendor's business registration (vendor). It is created as processing and finishes a few seconds later as verified, needs_review or failed, with a confidence score, flags and which fields each source matched.
POST /v1/vetting/checks
{ "type": "ffl_dealer", "license_number": "4-37-201-01-8K-70207", "business_name": "Hollow Pawn & Gun",
"premise_address": { "line1": "4409 Highway 41", "state": "TN", "postal_code": "37201" }, "reference": "dealer-8812", "recheck": true }
Names are compared without "LLC", "Inc" and word order; addresses without suite numbers and with standard abbreviations, so 410 Market Street, Suite 200 matches 410 MARKET ST. Flags include license_not_found, license_expired, license_expiring_soon, name_mismatch, premise_mismatch and premise_partial_match. With "recheck": true the license is looked up again every day and you get vetting.license.expiring 60 days before it expires.
The license listing is this sandbox's sample dealer directory and the business registry is generated sample data. A result helps you decide; it does not replace the transfer and record-keeping rules that apply to you.
Webhooks
POST /v1/webhooks with an https url (http only when the server operator allows private testing) and a list of events: vetting.check.completed, vetting.license.expiring, order.submitted, order.shipped, order.delivered, vendor.inventory.updated, support.message.created. The response carries the signing secret once. Each delivery is a JSON POST:
{ "id": "evt_...", "event": "vetting.check.completed", "created_at": "2026-11-17T15:04:11.000Z",
"data": { "id": "chk_...", "status": "needs_review", "flags": ["premise_mismatch"], "reference": "dealer-8812" } }
Check the signature header before trusting a delivery. It reads t=<unix seconds>,v1=<signature>, where the signature is the hex HMAC-SHA256 of t + "." + body keyed with your secret. Compare in constant time and reject timestamps more than a few minutes old. The public header name is RollStamp-Signature.
const [t, v1] = header.split(',').map((p) => p.split('=')[1]);
const expected = crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex');
const got = Buffer.from(v1 || '');
const ok = got.length === Buffer.byteLength(expected) && crypto.timingSafeEqual(got, Buffer.from(expected)) && Math.abs(Date.now() / 1000 - Number(t)) < 300;
Answer with any 2xx within 8 seconds. Anything else is retried after 1 minute, 5 minutes, 30 minutes and 2 hours, then marked failed. Redirects are not followed, and URLs that resolve to private or local addresses are refused unless the operator turns on the private-address allowance. GET /v1/webhooks/{id}/deliveries shows the attempt count, latest status code and last error for each delivery; POST /v1/webhooks/{id}/test queues a test delivery.
EDI and ERP
GET /v1/orders/{order_id}/edi returns an ANSI X12 004010 850 purchase order for each distributor or vendor order. POST /v1/edi/inbound reads what a partner sends back, as {"x12": "..."}:
| Set | What happens |
|---|---|
| 855 | The order is marked acknowledged, or rejected by the partner. |
| 856 | Carrier and tracking number go onto the order; it becomes shipped and order.shipped fires. |
| 810 | The invoice is recorded; its total is compared with the order's product subtotal. |
| 846 | A portal vendor's inventory is replaced (the sender id must match the vendor's id or edi_id). |
The response lists a result per transaction set and the 997 acknowledgment to send back. Set your interchange ids with PUT /v1/edi/settings. Documents move over this API. An AS2, SFTP or VAN connection to the partner is not part of this build and is set up separately.
For an ERP or accounting system, GET /v1/erp/export?type=orders|purchase_order_lines|shipments|invoices&format=json|csv&since=2026-11-01 returns flat rows you can import into your system. since is optional. Values that a spreadsheet could read as a formula are prefixed with an apostrophe in the CSV.
Vendors and the portal
Add your own vendors with POST /v1/vendors. The response carries a portal token (shown once) for the vendor to sign in at /portal/, where they upload an inventory CSV with sku and qty columns (optional upc, cost and name), see their purchase orders and add tracking. The same actions are available to them as /v1/portal/* routes with Authorization: Bearer <portal token>.
Vendor items whose UPC is in the master catalog and that carry a positive cost become one more source in your catalog: search, quotes and sourcing_mode: "optimal" orders can choose the vendor, the purchase order appears in its portal with status sent_to_vendor, and the tracking it enters flows back to the order. Items with an unknown UPC are stored but not listed, because their product class and restrictions are not known. Disable a vendor with PUT /v1/vendors/{id} and replace its token with POST /v1/vendors/{id}/token.
Support chat
Open a conversation with POST /v1/support/conversations ({"message": "..."}), add to it with POST .../{id}/messages, and read replies with GET .../{id}. The page at /support/ does this for you: sign in with your API key. Support staff use the same page with the admin token (or /__sandbox/support). A staff reply raises support.message.created.
MCP connector
The connector at /mcp speaks the Model Context Protocol. An MCP client can call a fixed set of tools. Most read account records: orders, why an order was routed where it was, a side-by-side comparison of your sources, catalog search, dealer lookups, restriction checks, carrier rates and vetting checks. One tool starts a vetting check, and one previews and applies a bulk catalog change when writes are allowed. For browser approval, the client must support a remote HTTP MCP server and OAuth 2.1 with PKCE. A client that can set request headers can use an API key instead. This build has not tested every client.
- Switch it on:
PUT /v1/mcp/settings {"enabled": true}. It is off by default. - In the client, add a remote MCP server and give it this server's address followed by
/mcp. - Your browser opens an approval page here. Enter an API key to approve.
A client that can set request headers can skip the approval page. Send Authorization: Bearer <API key> or x-api-key: <API key> from an address on the key's allowlist. That path has no connection record, and writes follow only the account setting.
Bulk changes (activating or deactivating sources, or changing the minimum quantity to list) need "allow_writes": true in the settings. An OAuth link also needs the box ticked on its approval page. Each change returns a preview first, with the number of catalog offers before and after, and is applied only when the client sends the preview's confirmation token back. A change that would remove more of the catalog than your delete threshold cannot be applied this way. GET /v1/mcp/settings lists OAuth links and DELETE /v1/mcp/connections/{id} removes one; it does not revoke a key used directly. Tool calls count against your rate limits.
Errors
| Status | Code | What to do |
|---|---|---|
| 400 | invalid_parameter / invalid_request / invalid_json / invalid_upc | The body or a field is missing or malformed. The request is rejected before any change. |
| 400 | schema_validation_failed | Configuration rejected; details lists every {path, message}. Nothing was saved. |
| 400 | missing_strong_signal | A fraud call needs an address line, an email or a phone. |
| 401 | missing_api_key | Send the x-api-key header. |
| 403 | invalid_api_key / key_disabled | Unknown, disabled or cancelled key. |
| 403 | ip_whitelist_required | The key has no registered server IPs yet. |
| 403 | ip_not_allowed | This caller address is not on the key allowlist. |
| 403 | ffl_not_associated_with_order | License documents are only for FFLs used by your own orders. |
| 404 | not_found / product_not_found / ffl_not_found / order_not_found / report_not_found | No match: an unknown path, a missing image, or a record not on this account. |
| 409 | no_active_distributors / no_validated_distributors | Activate sources, then check their credentials. |
| 409 | duplicate_order | That order_id was already placed. Do not retry with a new id. |
| 400 | invalid_ffl | The dealer license is malformed, unknown or inactive. |
| 409 | sourcing_unavailable | The named source cannot fill a line. |
| 409 | restricted_destination / fulfillment_not_configured | The order cannot ship as requested. |
| 409 | validation_failed | A save would remove too much of the catalog. |
| 413 | payload_too_large | Bodies are capped at 1 MB. |
| 429 | rate_limited | Wait Retry-After seconds, then retry with backoff. |
| 429 | catalog_request_cooldown | One catalog download per 20 minutes; send last_version to poll for free. |
| 429 | order_volume_limit / fraud_limit_exceeded | The order or fraud cap was reached. |
| 401 | invalid_vendor_token / unauthorized / invalid_token | Portal or connector credentials are missing, wrong or expired. |
| 403 | vendor_disabled / mcp_disabled / bulk_changes_not_allowed | The vendor, the connector or bulk changes are switched off for the account. |
| 404 | check_not_found / webhook_not_found / vendor_not_found / conversation_not_found / connection_not_found | Nothing with that id on your account. |
| 400 | invalid_edi | The X12 text could not be read (ISA segment or ST/SE pairs). |
| 409 | webhook_limit / vendor_limit / too_many_open_conversations / conversation_closed / preview_stale | A limit was reached, or the thing changed since you looked. |
| 500 | internal_error | Retry with backoff. |
The sandbox
This sandbox uses generated sample data: sources, products, dealers, rules and reports are made up, and orders are simulated. Nothing ships. When the site is opened as plain pages the API runs in the browser and keeps data there; run it with Node (npm run api) to serve the same routes to another program.