=== FFL Connect for WooCommerce ===
Contributors: jeffvato
Tags: ffl, firearms, woocommerce, checkout, dealer locator
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Let customers pick a licensed FFL dealer on a map at checkout, so every firearm order ships to a verified dealer.

== Description ==

Selling firearms online means every order has to ship to a Federal Firearms Licensee (FFL), not to the customer. FFL Connect adds that step to your WooCommerce checkout.

When a cart contains a product that needs an FFL transfer, the customer searches by ZIP code, sees nearby licensed dealers in a list and on a map, and picks one. The chosen dealer becomes the order's shipping address and the dealer's FFL number is saved on the order, so you do not have to chase customers for dealer details after they pay.

= What it does =

* Adds an FFL dealer picker (ZIP code search, results list and interactive map) to the checkout.
* Appears only when the cart contains a product that needs an FFL transfer.
* Lets you mark products one by one ("Requires FFL transfer") or by whole product category.
* Sets the order's shipping address to the chosen dealer.
* Shows the dealer's FFL number on the order screen and in order emails.
* Re-checks the chosen dealer on your server before the order is accepted. If the check cannot be completed, the order is not placed.
* Works with WooCommerce High-Performance Order Storage.

= What you need =

* WooCommerce, using the classic checkout (the `[woocommerce_checkout]` shortcode). The dealer picker does not appear on the block-based checkout.
* An FFL Connect API key. The plugin is free; the dealer database it searches is a paid service. Keys are available at [fflconnect.net](https://fflconnect.net/pricing/).

= About the dealer data =

Dealer records come from the list of active licensees published by the U.S. Bureau of Alcohol, Tobacco, Firearms and Explosives (ATF) and are refreshed monthly. Dealers known not to accept transfers are left out of results.

This plugin helps you collect a dealer for each firearm order. It does not give legal advice, and it does not replace your own compliance procedures, including obtaining a copy of the receiving dealer's licence where the law requires it.

== External services ==

This plugin relies on two external services.

= FFL Connect API (api.fflconnect.net) =

Used to find dealers and to confirm the dealer a customer selected. It is provided by Fuzzy Holdings LLC, the author of this plugin.

* When a customer searches for dealers at checkout, your server sends the ZIP code and search radius they entered, together with your store's API key.
* When an order with an FFL item is placed, your server sends the selected dealer's FFL licence number, together with your store's API key, to confirm the dealer.
* When you press "Test connection" on the settings page, your server sends one test search with your API key.

No customer names, addresses, emails or order contents are sent. Requests are made by your server, so your customers' browsers do not contact this service.

[Terms of Service](https://fflconnect.net/terms-of-service/) | [Privacy Policy](https://fflconnect.net/privacy-policy-2/)

= OpenStreetMap map tiles (tile.openstreetmap.org) =

Used to draw the map in the dealer picker. When the picker is shown, the customer's browser requests map images directly from OpenStreetMap's servers, which means OpenStreetMap receives the customer's IP address and the map area being viewed. The service is provided by the OpenStreetMap Foundation.

[Tile usage policy](https://operations.osmfoundation.org/policies/tiles/) | [Privacy Policy](https://osmfoundation.org/wiki/Privacy_Policy)

The Leaflet map library itself is bundled with the plugin and is not loaded from another site.

== Installation ==

1. Install and activate the plugin. WooCommerce must be active.
2. Go to **WooCommerce > FFL Connect** and enter your API key. Press **Save Changes**, then **Test connection**.
3. Tell the plugin which products need an FFL transfer: tick product categories on the same settings page, or tick **Requires FFL transfer** on individual products (Product data > General).
4. Make sure your checkout page uses the `[woocommerce_checkout]` shortcode.
5. Add an FFL product to your cart and open the checkout to see the dealer picker.

== Frequently Asked Questions ==

= Is the plugin free? =

The plugin is free and open source. It needs an API key for the FFL Connect dealer database, which is a paid annual service.

= Does it work with the block checkout? =

No. The dealer picker is added to the classic checkout only. If your checkout page uses the Checkout block, replace it with the `[woocommerce_checkout]` shortcode.

= What happens if a customer does not choose a dealer? =

The order is not accepted. They see a message asking them to search for and select a dealer.

= What happens if the dealer service cannot be reached? =

Customers see a message that the search is unavailable, and orders containing FFL items are not accepted until it is back. Orders without FFL items are not affected.

= Can a customer type in a dealer that is not in the results? =

No. Only dealers returned by the search can be selected, and the selection is confirmed again on your server.

= Where do I see the chosen dealer? =

On the order screen, under the shipping address, and in order emails. The dealer's name and address are also the order's shipping address.

= Does it support product variations? =

Yes. If the product, the selected variation, or one of the product's categories is marked as needing an FFL, the picker appears.

== Screenshots ==

1. The dealer picker on the checkout page: ZIP code search, map and results list.
2. A selected dealer, confirmed at the top of the picker.
3. The settings page under WooCommerce > FFL Connect.
4. The "Requires FFL transfer" checkbox on a product.

== Changelog ==

= 1.1.0 =
* First release on WordPress.org.
* New settings page under WooCommerce > FFL Connect with a connection test.
* Mark whole product categories as needing an FFL transfer, in addition to individual products.
* Dealer results are listed alphabetically.
* The picker now inherits your theme's colours and works on dark themes.
* The map library is bundled with the plugin.
* Order data is stored through WooCommerce's order API (High-Performance Order Storage compatible).
* The dealer's FFL number is included in order emails.

== Upgrade Notice ==

= 1.1.0 =
First release on WordPress.org. The settings page has moved to WooCommerce > FFL Connect; your saved API key is kept.
