Firearms and FFL dealers
Early access
A firearm ships to a licensed dealer, not to the buyer. By default, every order from your BigCommerce store gets the dealer step, and ShotPay asks Master FFL to rule on where it can ship — nothing to tag, nothing to switch on. Two settings under FFL change that: asking only for products you flag as regulated, which is also the only way Master FFL's ruling can remove the dealer step entirely, and having the shopper choose their dealer on your own storefront rather than at the ShotPay checkout. See Where the dealer is chosen. Whichever way it is chosen, ShotPay checks that dealer with Master FFL and the dealer goes on your BigCommerce order as the ship-to.
If your business does not hold an FFL — you told ShotPay so during onboarding — none of this applies: there is no dealer step, no Master FFL ruling and no FFL settings in the panel, so your store can only take orders that ship to the shopper.
- The shopper presses the ShotPay button. On the default setup your storefront shows nothing about a dealer. If Choose the dealer on the storefront is on and the cart needs one, the shopper chooses a dealer next to the button itself before it will do anything — see Choosing on the storefront.
- At the ShotPay checkout, once the shopper has signed in and their address is on file, ShotPay sends the cart and the shopper's ZIP code to Master FFL. The page reads Checking how your order can ship until Master FFL answers.
- Master FFL rules on the whole order:
- It ships to the shopper. With Only ask for a dealer on regulated products on, there is no dealer step and the shopper goes straight to payment; a default dealer they saved earlier, or one they chose on the storefront, is not used. On the default setup, the order still needs a dealer regardless of this ruling.
- It needs a dealer, or one who can take NFA transfers. The shopper chooses one in Master FFL's selector. If the order holds a National Firearms Act (NFA) item, the selector offers only dealers who can take NFA transfers.
- It is blocked. The checkout says the order cannot ship to that address and offers nothing further. The wording comes from Master FFL's rules.
- When the shopper chooses a dealer, ShotPay checks it with Master FFL before keeping it. A dealer Master FFL refuses is not kept, and the shopper chooses again.
- When the plan opens, the order in your BigCommerce admin ships to that dealer.
The ruling is for the ZIP code on the shopper's ShotPay account. If they change it, ShotPay asks Master FFL again before the plan can open.
What the shopper goes through is on Checkout Flow. This page covers what happens when Master FFL cannot rule, and what you receive.
Where the dealer is chosen
Two switches, both under FFL in the panel or on the dashboard, change whether the dealer step shows at all and where the shopper goes through it. With Only ask for a dealer on regulated products on, a cart with no flagged product skips Master FFL entirely and gets no dealer step — so flag every firearm. On the default setup, every order reaches Master FFL and keeps the dealer step regardless of its ruling: Master FFL can still block the order or restrict it to NFA-capable dealers, but cannot turn the step off. If Master FFL cannot be reached, the default setup goes ahead without its ruling — the shopper still gets the dealer step and can pay, but no block and no NFA limit is applied to that order.
| Setting | Default | What it does |
|---|---|---|
| Only ask for a dealer on regulated products | Off — every product asks | Limits the dealer step to products you flag as regulated. See Flagging a product as regulated. |
| Choose the dealer on the storefront | Off — choose at the ShotPay checkout | Moves the dealer step onto your storefront, next to the ShotPay button, before the shopper ever reaches ShotPay. |
| Dealer selector position | Above the button | Where the storefront's dealer step sits relative to the ShotPay button. Only matters while the setting above is on. |
Flagging a product as regulated
With Only ask for a dealer on regulated products on, ShotPay reads one
custom field off each BigCommerce product to decide whether it needs a dealer.
It checks, case-insensitively, for a field named ffl_required, ffl,
is_ffl, requires_ffl, or regulated, and treats any value other than
blank, false, 0, no, n, or off as "yes, this needs a dealer." If a
product has an ffl_required field, that field alone decides, even when it
says no — the other names are only checked when it is missing. A product
carrying none of those fields is treated as not regulated. A cart with one
regulated line still needs a dealer for the whole order, whatever else is in
it.
If BigCommerce cannot be read when the shopper presses the ShotPay button, ShotPay refuses layaway for that product or cart rather than letting it through unchecked. If it cannot be read later, at the ShotPay checkout, ShotPay treats the cart as regulated and asks Master FFL.
Choosing on the storefront
With Choose the dealer on the storefront on, a shopper whose cart needs a dealer sees the step beside the ShotPay button itself, before pressing it does anything:
- The shopper presses Choose your FFL dealer, which opens Master FFL's selector in a window of its own, not a panel on the page. Master FFL only lets its selector run under pages it has registered, and your storefront is not one of them, so ShotPay cannot show it inline or in a frame on your site. If the shopper's browser blocks the pop-up, they are told to allow pop-ups for your site and choose again.
- ShotPay checks the pick with Master FFL before accepting it, the same as it does at the checkout.
- The button turns on, now showing the chosen dealer with a way to change it. The choice is remembered for the day, on that device and that store, so a shopper who keeps shopping does not choose again on their next visit to the button.
When the shopper presses the ShotPay button, ShotPay checks the dealer with Master FFL again, since the choice can be up to a day old. The shopper is not asked to choose again at the checkout, unless Master FFL rules that the order needs a dealer who takes NFA transfers.
With this setting off, the only dealer step is the one at the ShotPay checkout described above, and the storefront shows nothing about a dealer.
When Master FFL cannot rule
| Situation | What the shopper sees | What you do |
|---|---|---|
| Master FFL has no record of your store's domain or of a product in the cart | The dealer step, as if the order needed one. ShotPay keeps the dealer step instead of letting a firearm ship without a ruling. | Contact ShotPay. Master FFL needs your store's domain registered before it can rule on your orders. |
| Master FFL is unreachable or answers with an error, with Only ask for a dealer on regulated products on | We could not check your order, with a Try again button. The dealer step and the payment step stay hidden until Master FFL answers. | Nothing. |
| Master FFL is unreachable or answers with an error, on the default setup | Nothing — the dealer step and the payment step show as usual. No block and no NFA limit is applied to that order. | Nothing. |
| Master FFL refuses ShotPay's own access to its rules | We could not check your order, with a message that trying again will not help and to contact the store. There is no Try again button, and the dealer step and the payment step stay hidden. | Contact ShotPay. |
| Master FFL refuses the shopper's ZIP code | A message that ShotPay could not use that ZIP code to check the order, with no Try again button. | The shopper corrects the ZIP code on their ShotPay account. |
Live rulings
ShotPay is still getting live access to Master FFL's rules. Until it has that access, every live order from your store keeps the dealer step. In sandbox, Master FFL answers from test scenarios, so the dealer step does not follow what is in the cart.
Your Master FFL credentials
ShotPay uses Master FFL to check each dealer a shopper chooses and to look up the dealer's name and address. It needs a Master FFL API key and secret to do that. You find them under FFL → Master FFL connection, in the panel or on the dashboard. The ruling on each order does not use them: ShotPay asks for that with its own access.
| Do you have your own Master FFL account? | Whose credentials ShotPay uses |
|---|---|
| Off (the default) | ShotPay's own Master FFL account. There is nothing for you to enter. |
| On | Yours. Enter your API key and API secret. |
If you turn it on and have not saved a key and secret, ShotPay does not fall back to its own account. Shoppers cannot have a dealer checked until you save a pair.
- Saving. Leave a field blank to keep what is saved, so you can change the key without retyping the secret. The secret is never shown again, and the key only masked, ending in its last four characters.
- Test connection. Checks the pair against Master FFL without saving anything you have typed; a blank field is tested using the saved value. A pass shows a green tick next to the button. Only a pass on the saved pair is remembered, so the tick is still there when you come back. Changing the key or the secret clears it until you test again.
- Remove. Deletes the saved key and secret and turns the setting back off, so ShotPay's own account is used again.
Credentials are saved separately for sandbox and for live.
ShotPay does not send the transfer to Master FFL yet
Today your credentials are used to check dealers and to read their details. ShotPay does not create the Master FFL transfer for you. The shopper's transfer PIN goes to Master FFL when the dealer is checked, and is never written to BigCommerce.
What lands in your BigCommerce order
The order is created when the plan opens, in the same statuses as any other plan — see Dashboard and orders. For an order that needs a dealer, it also carries the following.
The ship-to address
| Field | Value |
|---|---|
| Name | The shopper's name, so the dealer receives it in the buyer's name. |
| Company | Dealer trade name (FFL #12345678) — the dealer's name and its eight-character short licence number. |
| Street, city, state, ZIP | The dealer's, read from Master FFL when the order is created: its shipping address if Master FFL has one on file, otherwise its premises address. |
| Phone | The dealer's ATF-registered phone number, as Master FFL holds it. |
| The shopper's. | |
| Shipping method | The method the shopper picked, such as UPS Ground. Ship to FFL dealer when no shipping was priced. |
Shipping is priced to the dealer's address, not the shopper's, with your own shipping methods. See Shipping.
The billing address is the shopper's own, as on any ShotPay order.
The staff note names the plan and ends with Ships to FFL dealer: and the
licence number, so you can see it in the order list without opening the address.
Form fields and a metafield
If your store defines shipping-address form fields with these exact names, ShotPay fills them in:
| Form field | Value |
|---|---|
FFL-License-Number-Short |
The eight-character licence number. |
FFL-License-Number |
The dealer's full licence number, dashes included (for example 1-82-012-07-8A-04711). |
FFL-Name |
The dealer's trade name. |
FFL-Expiration-Date |
The licence expiry, when Master FFL supplies one, written the way Master FFL writes it (MM/DD/YY, for example 06/30/27). |
Each is written in its own call, so a store that has defined some of them but
not FFL-License-Number still gets the rest filled in. A store that has not
defined a given field keeps its order and ship-to exactly as above; that one
field is skipped, with nothing to fix.
Every such order also gets a metafield for anything that reads the order
afterwards. Its namespace is shotpay, its key is ffl, and it is readable by
other apps. Its value is JSON:
{
"license_number_short": "12345678",
"trade_name": "Black Powder Supply",
"phone": "2085550134",
"address": {
"street": "4 Ridge Road",
"city": "Boise",
"state": "ID",
"zip": "83702"
},
"license_expires_on": "06/30/27"
}
license_expires_on is null when Master FFL does not give one. ShotPay
retries the form fields and the metafield if BigCommerce is briefly unavailable.
If BigCommerce refuses them, the order is left as it is.
When the dealer's address cannot be read
The order is still created, so stock stays reserved. If Master FFL has no record of the dealer, or gives no usable address, the order has no shipping address and its staff note ends with:
Master FFL could not supply this dealer's address. Confirm it before shipping.
The note still names the licence number. Such an order has no form fields and no metafield either, since there is nothing to put in them. If Master FFL is simply unreachable, ShotPay retries for a while before it creates the order this way.
Do not ship an order with that note until you have confirmed the dealer
There is no ship-to to fall back on. Look the licence number up and add the address yourself before the order moves to fulfilment.
Testing
- Preview checkout on the ShotPay dashboard has a Require an FFL dealer switch, so you can see the dealer step without a firearm in a cart, and a Choose the dealer at the button switch beside it to preview Choosing on the storefront instead of the checkout step. A preview has no BigCommerce cart, so Master FFL does not rule on it either way.
- In sandbox, Master FFL answers from test scenarios, so the dealer step does not follow what is in your cart.
- A plan opened in sandbox still creates a real order with the dealer on it. Its staff note starts with TEST — ShotPay sandbox, as on any sandbox plan.
If something looks wrong
| You see | Likely cause |
|---|---|
Shoppers are told We could not check that dealer just now. Try again in a moment. |
Master FFL could not be reached, or no usable credentials are saved. If Do you have your own Master FFL account? is on, check that a key and secret are saved and press Test connection. |
| We could not check your order | ShotPay could not get a ruling from Master FFL, with Only ask for a dealer on regulated products on. The shopper presses Try again. If it keeps happening, contact ShotPay. On the default setup, this never shows: Master FFL being unreachable does not hold the order there, and the shopper sees the dealer step and can pay. |
| We could not check how your order can ship, and trying again will not help | Master FFL refused ShotPay's own access to its rules, for example because it rejected a key or has not enabled your store for ShotPay. Contact ShotPay. |
| This order cannot be shipped to your address | Master FFL's rules block an item in the cart for the shopper's ZIP code. The text under it comes from Master FFL. |
| A dealer step on an order you expected to ship to the shopper | Only ask for a dealer on regulated products is off, so every order gets the dealer step. Turn it on and flag your firearms. If it is already on: Master FFL has no record of your store's domain or of a product in the cart, so ShotPay kept the dealer step. Contact ShotPay. In live, it can also mean ShotPay does not have live access to Master FFL's rules yet. |
| No dealer step on a firearm | Only ask for a dealer on regulated products is on, and either the product is not flagged (see the row below) or Master FFL ruled that the order ships to the shopper. Its rules decide that, so ask Master FFL how it classifies the product. |
| A shopper is asked to choose a dealer again after they already did | Master FFL stopped accepting the dealer, or ruled again because the ZIP code on the shopper's account changed. |
| The ShotPay button stays greyed out next to a Choose your FFL dealer prompt | Choose the dealer on the storefront is on and the cart needs a dealer; the shopper has to choose before the button will open a checkout. If the prompt does nothing, their browser blocked the pop-up — see Choosing on the storefront. |
| The ShotPay button does not show on products that need a dealer (on the default setup, that is every product) | Choose the dealer on the storefront is on, and your own Master FFL key and secret are not saved or have not passed Test connection. |
| A product never gets the dealer step even with Only ask for a dealer on regulated products on | Its BigCommerce custom field is not named ffl_required, ffl, is_ffl, requires_ffl, or regulated, or its value reads as a "no" — see Flagging a product as regulated. |
| An order with no shipping address | See When the dealer's address cannot be read. |
| The form fields are empty | Your store has no shipping-address form fields with the exact names above. |