Rollmark API

The Rollmark API lets a store's website, a plugin or an inventory system work with the store's own Rollmark data: the products as the store lists them, the orders a shopper makes with a chosen FFL, the store's orders to distributors, the stock the store keeps by hand, and a call to your server when any of that changes.

Everything is under one address:

https://app.getrollmark.com/api/v1

There is no second host. FFL Checkout (find an FFL near a shopper, send the order made with it) is the same API and lives under /checkout. The reference is made from the API's own definition, openapi.yaml, which you can load into any tool that reads OpenAPI 3.1.

You build against version 1. New endpoints and fields may be added; nothing is removed or changed in meaning, and a change that would break you is announced at least six months ahead. Read the promise.

What you can do

Some things are deliberately not in the API: sending a distributor order, anything that spends the store's money, FastBound items (FastBound stays the record for guns), the store's cost and pricing rules. They are for the store's staff in Rollmark. Why.

Quickstart

You need a store on Rollmark and an owner or manager to make you a key.

1. Make a key. In the dealer app: Settings, API keys. Name it ("Order plugin"), choose Catalog, then Private, and tick only what the key needs. Nothing is ticked by default. Press Make key. The key is shown once; copy it into your server's secrets. Rollmark stores only a hash of it and cannot show it again.

2. Call the API. Put the key in an Authorization header and ask who you are:

export ROLLMARK_KEY=rm_prv_...   # the key you copied

curl https://app.getrollmark.com/api/v1/me \
  -H "Authorization: Bearer $ROLLMARK_KEY"

The answer names the store, the key and what the key may do, so a plugin can check a pasted key when it is installed:

{ "data": { "store": { "id": 7, "name": "…" }, "key": { "id": "a1b2c3d4", "kind": "private", "family": "catalog", "permissions": ["orders:read", "orders:write"] }, "plan": "pro", "features": { "distributor_orders": "placed", "inventory": true }, "limits": { "requests_per_minute": 600 } } }

3. Read something. With orders:read:

curl "https://app.getrollmark.com/api/v1/orders?status=open&limit=20" \
  -H "Authorization: Bearer $ROLLMARK_KEY"

The answer is { "data": [ … ], "next_cursor": "…" }. Pass next_cursor back as cursor for the next page: Pagination.

4. Change something, safely. Every write takes an Idempotency-Key, so a request that timed out can be sent again without doing the thing twice: Idempotency.

curl -X POST "https://app.getrollmark.com/api/v1/orders/<id>/cancel" \
  -H "Authorization: Bearer $ROLLMARK_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Customer asked to cancel"}'

5. Be told instead of asking. Register a webhook and Rollmark calls your server when an order ships: Webhooks.

Where to go next

• Authentication and permissions: the four kinds of key, and what each permission allows.
• Errors: one envelope, stable codes, a request id to quote to support.
• Rate limits: headers on every answer.
• Build your own platform integration: a store system Rollmark has no plugin for.
• Keep Rollmark stock in sync from your inventory system.
• Reference: every endpoint.