03API reference

Version 1.0.0Made from openapi.yaml

FFL Checkout

Server-to-server only. Find an FFL near a shopper and send Rollmark the order that was made with it.

GET/checkout/fflsFFLs near a ZIP GET/checkout/ffls/{id}One FFL GET/checkout/preferredThe dealer's preferred FFLs POST/checkout/ordersSend the order a shopper made with a chosen FFL GET/checkout/orders/{id}Where an order stands POST/checkout/orders/{id}/matchThe store's own order now exists

FFLs near a ZIP

GET/checkout/ffls

FFL Checkout key (rm_chk_), from a server

Server-to-server only (no CORS; a request with an Origin or Sec-Fetch-Site header is refused). Takes a checkout key. The store's plan must include FFL Checkout. Preferred FFLs first, then by distance; the store's blocked FFLs are left out. This is ATF's monthly list, not a live ATF check.

Parameters

Name	In	Type	Description
`zip`required	query	`string`	Pattern `^[0-9]{5}$`.
`radius`	query	`integer`	Miles. Default 25 Default 25. 1 to 100.
`limit`	query	`integer`	Default 25. 1 to 50.
`page`	query	`integer`	Default 1. At least 1.

Responses

200A page of FFLs.

Headers: X-Request-Id, X-RateLimit-Remaining

Field	Type	Description
`data`required	`object[]`
data[].`id`required	`string`	The 13-character licensee id.
data[].`license_number`required	`string`
data[].`name`required	`string`
data[].`address`required	`object`
data[].address.`street`required	`string \| null`	Null where the directory hides the street.
data[].address.`city`required	`string`
data[].address.`state`required	`string`
data[].address.`zip`required	`string`
data[].`phone`	`string \| null`
data[].`license_type`required	`object`
data[].license_type.`code`required	`string`
data[].license_type.`label`required	`string`
data[].`expires`required	`string (date) \| null`
data[].`distance_miles`	`number \| null`
data[].`claimed`	`boolean`
data[].`preferred`required	`boolean`
data[].`accepts_transfers`required	`"yes" \| "no" \| "unknown"`
data[].`transfer_fee`	`number \| null`
data[].`hours`	`string \| null`
data[].`contacts`	`object[]`
data[].contacts[].`kind`required	`"email" \| "phone"`
data[].contacts[].`value`required	`string`
data[].contacts[].`label`	`string`
`page`required	`integer`
`limit`required	`integer`
`total`required	`integer`
`list_as_of`required	`string (date) \| null`

Errors400401403404429503in the error envelope.

Example

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

One FFL

GET/checkout/ffls/{id}

FFL Checkout key (rm_chk_), from a server

id is the licensee id or a license number written any way. One 404 for every reason (not listed, hidden, a collector, unknown).

Parameters

Name	In	Type	Description
`id`required	path	`string`

Responses

200The FFL.

Headers: X-Request-Id

Field	Type	Description
`data`required	`object`
data.`id`required	`string`	The 13-character licensee id.
data.`license_number`required	`string`
data.`name`required	`string`
data.`address`required	`object`
data.address.`street`required	`string \| null`	Null where the directory hides the street.
data.address.`city`required	`string`
data.address.`state`required	`string`
data.address.`zip`required	`string`
data.`phone`	`string \| null`
data.`license_type`required	`object`
data.license_type.`code`required	`string`
data.license_type.`label`required	`string`
data.`expires`required	`string (date) \| null`
data.`distance_miles`	`number \| null`
data.`claimed`	`boolean`
data.`preferred`required	`boolean`
data.`accepts_transfers`required	`"yes" \| "no" \| "unknown"`
data.`transfer_fee`	`number \| null`
data.`hours`	`string \| null`
data.`contacts`	`object[]`
data.contacts[].`kind`required	`"email" \| "phone"`
data.contacts[].`value`required	`string`
data.contacts[].`label`	`string`
data.`status`required	`"active" \| "expired" \| "inactive"`
data.`blocked`required	`boolean`
data.`list_as_of`required	`string (date) \| null`
data.`ez_check_url`required	`string (uri)`
data.`notice`required	`string`

Errors400401403404429503in the error envelope.

Example

Shell
curl "https://app.getrollmark.com/api/v1/checkout/ffls/<id>" \
  -H "Authorization: Bearer $ROLLMARK_KEY"

The dealer's preferred FFLs

GET/checkout/preferred

FFL Checkout key (rm_chk_), from a server

Parameters

Name	In	Type	Description
`limit`	query	`integer`	Default 50. 1 to 50.
`page`	query	`integer`	Default 1. At least 1.

Responses

200A page of FFLs.

Headers: X-Request-Id

Field	Type	Description
`data`required	`object[]`
data[].`id`required	`string`	The 13-character licensee id.
data[].`license_number`required	`string`
data[].`name`required	`string`
data[].`address`required	`object`
data[].address.`street`required	`string \| null`	Null where the directory hides the street.
data[].address.`city`required	`string`
data[].address.`state`required	`string`
data[].address.`zip`required	`string`
data[].`phone`	`string \| null`
data[].`license_type`required	`object`
data[].license_type.`code`required	`string`
data[].license_type.`label`required	`string`
data[].`expires`required	`string (date) \| null`
data[].`distance_miles`	`number \| null`
data[].`claimed`	`boolean`
data[].`preferred`required	`boolean`
data[].`accepts_transfers`required	`"yes" \| "no" \| "unknown"`
data[].`transfer_fee`	`number \| null`
data[].`hours`	`string \| null`
data[].`contacts`	`object[]`
data[].contacts[].`kind`required	`"email" \| "phone"`
data[].contacts[].`value`required	`string`
data[].contacts[].`label`	`string`
`page`required	`integer`
`limit`required	`integer`
`total`required	`integer`
`list_as_of`required	`string (date) \| null`

Errors400401403429503in the error envelope.

Example

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

Send the order a shopper made with a chosen FFL

POST/checkout/orders

FFL Checkout key (rm_chk_), from a server

Creates a pending order (or an open, matched one when store_order_number is sent). Idempotent on intake_ref: the same body again is 200 with Idempotent-Replay: true; a different body is 409 intake_conflict. At most 256 KB. No card data, ever: a field named like card data is 400 card_data_rejected.

Request body

Field	Type	Description
`intake_ref`required	`string`	Your key for the order (a cart id). Makes the call idempotent. Up to 100 characters.
`store_cart_ref`	`string`	Up to 60 characters.
`store_order_number`	`string \| null`	When given Up to 40 characters.
`store_order_ref`	`string \| null`	Up to 60 characters.
`dealer_po`	`string \| null`	Up to 25 characters.
`shopper`required	`object`
shopper.`name`required	`string`
shopper.`email`required	`string (email)`
shopper.`phone`	`string`
`billing`required	`object`
billing.`name`	`string`
billing.`line1`required	`string`
billing.`line2`	`string`
billing.`city`required	`string`
billing.`state`required	`string`
billing.`zip`required	`string`
billing.`country`required	`string`
`shipping`	`object`
shipping.`name`	`string`
shipping.`line1`required	`string`
shipping.`line2`	`string`
shipping.`city`required	`string`
shipping.`state`required	`string`
shipping.`zip`required	`string`
shipping.`country`required	`string`
`ffl`	`object`	Required when any line ships to the FFL. `id` or `license_number`, any formatting.
ffl.`id`	`string`
ffl.`license_number`	`string`
`lines`required	`object[]`	1 to 200 items.
lines[].`sku`	`string`
lines[].`upc`	`string`	Pattern `^[0-9]{8,14}$`.
lines[].`mpn`	`string`
lines[].`manufacturer`	`string`
lines[].`title`required	`string`
lines[].`quantity`required	`integer`	1 to 10000.
lines[].`unit_price_cents`	`integer`	At least 0.
lines[].`needs_ffl`	`boolean`	A hint. The library decides; a disagreement is flagged `store_disagrees`.
`totals`	`object`
totals.`currency`	`string`	3 to 3 characters.
totals.`subtotal_cents`	`integer`
totals.`shipping_cents`	`integer`
totals.`tax_cents`	`integer`
totals.`total_cents`	`integer`

Responses

200The same order again (a replay).

Headers: Idempotent-Replay

Field	Type	Description
`data`required	`object`	Where an order stands. Never the shopper's details or billing.
data.`id`required	`string (uuid)`
data.`intake_ref`required	`string`
data.`status`required	`"pending" \| "open" \| "cancelled" \| "closed"`
data.`match_state`required	`"unmatched" \| "auto" \| "manual"`
data.`dealer_po`	`string \| null`
data.`store_order_number`	`string \| null`
data.`cancelled_reason`	`string \| null`
data.`ffl`	`object \| null`	The FFL as it was when the shopper chose it.
data.ffl.`id`	`string`
data.ffl.`license_number`	`string`
data.ffl.`name`	`string`
data.ffl.`phone`	`string \| null`
data.ffl.`street`	`string \| null`
data.ffl.`city`	`string`
data.ffl.`state`	`string`
data.ffl.`zip`	`string`
data.ffl.`list_as_of`	`string \| null`
data.`lines`required	`object[]`
data.lines[].`line_no`required	`integer`
data.lines[].`sku`	`string \| null`
data.lines[].`title`required	`string`
data.lines[].`quantity`required	`integer`
data.lines[].`ships_to`required	`"ffl" \| "customer"`
data.lines[].`ship_reason`required	`"firearm" \| "receiver" \| "library_not_firearm" \| "store_hint" \| "staff_override"`
data.lines[].`flagged`	`string \| null`	`store_disagrees` or `unknown_product` when staff should look.
data.lines[].`product_key`	`string \| null`
data.`received_at`required	`string (date-time)`
data.`updated_at`required	`string (date-time)`

201Created.

Errors400401403409413422429503in the error envelope.

Example

Shell
curl -X POST "https://app.getrollmark.com/api/v1/checkout/orders" \
  -H "Authorization: Bearer $ROLLMARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"intake_ref":"…","shopper":{"name":"…","email":"[email protected]"},"billing":{"line1":"…","city":"…","state":"…","zip":"…","country":"…"},"lines":[{"title":"…","quantity":1}]}'

Where an order stands

GET/checkout/orders/{id}

FFL Checkout key (rm_chk_), from a server

id is the order id or ref:<intake_ref>. Never returns the shopper's details.

Parameters

Name	In	Type	Description
`id`required	path	`string`

Responses

200The order.

Field	Type	Description
`data`required	`object`	Where an order stands. Never the shopper's details or billing.
data.`id`required	`string (uuid)`
data.`intake_ref`required	`string`
data.`status`required	`"pending" \| "open" \| "cancelled" \| "closed"`
data.`match_state`required	`"unmatched" \| "auto" \| "manual"`
data.`dealer_po`	`string \| null`
data.`store_order_number`	`string \| null`
data.`cancelled_reason`	`string \| null`
data.`ffl`	`object \| null`	The FFL as it was when the shopper chose it.
data.ffl.`id`	`string`
data.ffl.`license_number`	`string`
data.ffl.`name`	`string`
data.ffl.`phone`	`string \| null`
data.ffl.`street`	`string \| null`
data.ffl.`city`	`string`
data.ffl.`state`	`string`
data.ffl.`zip`	`string`
data.ffl.`list_as_of`	`string \| null`
data.`lines`required	`object[]`
data.lines[].`line_no`required	`integer`
data.lines[].`sku`	`string \| null`
data.lines[].`title`required	`string`
data.lines[].`quantity`required	`integer`
data.lines[].`ships_to`required	`"ffl" \| "customer"`
data.lines[].`ship_reason`required	`"firearm" \| "receiver" \| "library_not_firearm" \| "store_hint" \| "staff_override"`
data.lines[].`flagged`	`string \| null`	`store_disagrees` or `unknown_product` when staff should look.
data.lines[].`product_key`	`string \| null`
data.`received_at`required	`string (date-time)`
data.`updated_at`required	`string (date-time)`

Errors401403404429503in the error envelope.

Example

Shell
curl "https://app.getrollmark.com/api/v1/checkout/orders/<id>" \
  -H "Authorization: Bearer $ROLLMARK_KEY"

The store's own order now exists

POST/checkout/orders/{id}/match

FFL Checkout key (rm_chk_), from a server

Makes a pending order open. The same number again is 200; another number is 409 already_matched; an order staff cancelled is 409 order_cancelled.

Parameters

Name	In	Type	Description
`id`required	path	`string`

Request body

Field	Type	Description
`store_order_number`required	`string`	Up to 40 characters.
`store_order_ref`	`string`	Up to 60 characters.

Responses

200The order.

Field	Type	Description
`data`required	`object`	Where an order stands. Never the shopper's details or billing.
data.`id`required	`string (uuid)`
data.`intake_ref`required	`string`
data.`status`required	`"pending" \| "open" \| "cancelled" \| "closed"`
data.`match_state`required	`"unmatched" \| "auto" \| "manual"`
data.`dealer_po`	`string \| null`
data.`store_order_number`	`string \| null`
data.`cancelled_reason`	`string \| null`
data.`ffl`	`object \| null`	The FFL as it was when the shopper chose it.
data.ffl.`id`	`string`
data.ffl.`license_number`	`string`
data.ffl.`name`	`string`
data.ffl.`phone`	`string \| null`
data.ffl.`street`	`string \| null`
data.ffl.`city`	`string`
data.ffl.`state`	`string`
data.ffl.`zip`	`string`
data.ffl.`list_as_of`	`string \| null`
data.`lines`required	`object[]`
data.lines[].`line_no`required	`integer`
data.lines[].`sku`	`string \| null`
data.lines[].`title`required	`string`
data.lines[].`quantity`required	`integer`
data.lines[].`ships_to`required	`"ffl" \| "customer"`
data.lines[].`ship_reason`required	`"firearm" \| "receiver" \| "library_not_firearm" \| "store_hint" \| "staff_override"`
data.lines[].`flagged`	`string \| null`	`store_disagrees` or `unknown_product` when staff should look.
data.lines[].`product_key`	`string \| null`
data.`received_at`required	`string (date-time)`
data.`updated_at`required	`string (date-time)`

Errors400401403404409429503in the error envelope.

Example

Shell
curl -X POST "https://app.getrollmark.com/api/v1/checkout/orders/<id>/match" \
  -H "Authorization: Bearer $ROLLMARK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"store_order_number":"…"}'