Onboarding a consignment dealer

A manager sets up a new partner FFL once, before the first shipment. The wizard looks the dealer's license up with the ATF, creates their customer record, and opens the shared login they will use to see their rack.

Five steps stacked on one screen. A finished step collapses to a summary line.

Before you start

• Open /app/dealer-onboarding. You need the Sales Manager, Stock Manager or System Manager role.
• Consignment out must be switched on in FFL Settings. If it is off, the page shows a "feature is off" notice instead of the wizard.
• Have the dealer's FFL number in front of you, copied from their license.
• Agree a store mailbox with the dealer for the portal login, something like store@partner-guns.com. Do not use an employee's personal address. This is one shared login for the whole store, and it has to survive staff turnover there.
• The store needs a working outgoing email account, or the dealer will not get their password-setup link. See Integrations.

You can also reach this page from the Consignment Out page. Pick + New dealer… at the bottom of the dealer dropdown, and when you finish the wizard it offers to take you straight back to the shipment you were building.

Steps

All five steps live on one screen, stacked. Finished steps collapse to a summary line with a Change button.

1. Type the dealer's FFL number into Dealer's FFL number exactly as printed on their license, then click Look up. The check is a digit count, not a strict format, because a real FFL carries a letter in one segment.
2. Read the Dealer record card. It tells you which situation you are in. See the table below. When the wizard is building a new dealer, you can edit Store name here. That is the name your staff will see in the dealer dropdown, and changing it does not touch the ATF licensee name.
3. Click Continue, then type the shared store mailbox into Email and again into Confirm email. Type the second one from the dealer's own writing rather than pasting the first, so a typo in the address cannot survive.
4. Click Continue and check the Confirm summary. Tick I've checked this email address — the welcome email and the login both go to it.
5. Click Create dealer & open account. For a dealer who already exists in your system, the button reads Open portal account instead.
6. On the Done step, either click Done to leave, or Ship to this dealer → to jump to the Consignment Out page with this dealer already selected.

What the lookup can find

What the card says	What it means	What happens next
Already in your system — nothing to create.	A customer record already carries this FFL, with no portal login yet	Continue to step 3 and open their portal account.
This dealer can already sign in at /consignment.	They have a customer record and a login	The wizard stops here and shows the login masked. Steps 3 to 5 read "Nothing to do". Password resets are handled by an administrator, not here.
From your ATF file	No customer yet, but the license is already on file	Continuing creates the dealer from that ATF record.
Fetched from ATF eZ Check just now	No customer, no local record, so the license was looked up live	Continuing creates the dealer from what came back.
No ATF record for …	The ATF has no such number	The wizard stops. Nothing is created. Click Change number and check it against the license.
Couldn't reach ATF eZ Check.	The lookup service is unavailable right now	Click Try again in a moment. Nothing was created.

An outage is not a rejection

"Couldn't reach ATF eZ Check" and "No ATF record" mean different things. The first means the check did not happen. Never treat it as proof the dealer's license is bad, and never refuse a shipment on it.

One login belongs to one dealer

Before anything is created, the wizard refuses an email address that is already spoken for, and names where it went so you do not repeat a typo:

• The address already logs in for another dealer. Use a different address for this store.
• A contact record already carries that address for another dealer.
• The address belongs to some unrelated account in the system.

In every case, pick a different store mailbox. Do not repoint an existing login at a second store. The portal resolves a login to exactly one dealer, and a login attached to two would be locked out of the portal entirely.

What the system does

Everything below happens in one transaction. If any part fails, all of it rolls back, so there is never a half-built account to clean up. Re-running the wizard on the same FFL and the same email heals and links rather than duplicating.

• Creates the dealer's Customer record, or reuses the one that exists, linked to the ATF FFL Record for that license.
• Creates a User as a Website User carrying only the Consignment Dealer role.
• Creates or repairs a Contact holding that login, linked to the dealer's Customer.
• Queues a welcome email with a password-setup link.

The Done step tells you which of three things happened with that email. Read it before you leave the page.

What Done says	What it means	What to do
A welcome email is on its way	The message is queued	If it never arrives, check the Email Queue and the outgoing email account.
The account is created, but the welcome email couldn't be sent	The account is fine, only the mail failed	Fix the outgoing email account, then send the setup link from Reset Password on that user's record.
Nothing about a welcome	You re-ran on a login that already existed	Nothing to do. Only a brand new login gets a welcome.

The onboarding itself never fails because of the welcome email.

What the dealer receives

The dealer gets one email inviting them to complete their registration with your store, carrying a link that lets them set their own password. After that they sign in at your site's /login and land on /consignment, which is the only page they can reach. See The dealer portal for what they see there.

The Consignment Dealer role is portal only

The role the wizard assigns has no Desk access and no permissions on any record type. That is what keeps a dealer out of your system. A dealer who tries any /app address is refused, and the data interfaces refuse them by construction rather than by a rule someone has to remember to write.

Never add another role to a dealer login

Adding any second role to that user breaks the isolation the whole portal security model depends on, and can give a partner dealer a view of your inventory, your customers and your bound book.

The dealer's custody warehouse

The wizard does not create a warehouse. The first time you dispose a shipment to this dealer, the system creates one for them automatically, named Consignment Out - <dealer>. Guns you send them live in that warehouse, so your stock reports show them as still yours but not on your shelf. On the balance sheet the warehouse points at a Stock at Consignee asset account, which keeps "guns sitting at a partner FFL" as its own line rather than blending into stock in hand.

That warehouse's account is set once, at creation, and cannot be repointed after it has stock movements without a full accounting repost. Do not edit it.

Closing a dealer down

To cut off a login immediately, open that user's record and clear Enabled. When a dealer's staff changes, you do not need a new account. Reset the shared password and give it to their current store contact. That is the accepted trade-off of one shared login per store, and it is why accountability sits with the store rather than with whichever employee was at their counter.

To end the relationship completely, recall every remaining At Dealer gun first. See Shipping a consignment. A dealer's warehouse cannot be disabled while it still holds stock.

Troubleshooting

Message you see	What it means	Fix
That doesn't look like an FFL number	Fewer than nine digits typed	Retype it from the license.
Couldn't reach ATF eZ Check	The verification service is down	Click Try again shortly. Nothing was created.
No ATF record for …	The ATF has no such license	Check every digit against the license. A dealer cannot be created without an ATF record.
… already belongs to …	That email is another dealer's login	Use a different store mailbox.
That contact is already linked to another dealer	A contact record holds that address elsewhere	Use a different address.
… is already in use by another account	The address belongs to an unrelated account	Use a different address.
This FFL is expired	The license on file has lapsed	You can still open the account. You cannot ship to them until it is renewed. See Verifying an FFL.
Not Permitted, when the dealer signs in	The account is missing the role or is not a Website User	Have a System Manager check the account rather than hand-editing it.