Guides

WooCommerce - v3

Installation

  1. Download the Latest Version

    • Download the latest version of the MasterFFL Checkout plugin.

  2. Log in to WordPress Admin

    • Go to https://yourdomain.com/wp-admin
    • Enter your username and password

  3. Navigate to Plugins Section

    • In the left sidebar, click Plugins
    • Then select Add New

  4. Upload Plugin ZIP

    • At the top, click the Upload Plugin button
    • Click Choose File and select the plugin .zip file from your computer

  5. Install Plugin

    • Click the Install Now button
    • WooCommerce will upload and extract the plugin files

  6. Activate Plugin

    • Once installed, click Activate Plugin
    • The plugin will now be active and available in your WooCommerce site

  7. Configure the Plugin

    • Admin → MasterFFL Checkout

Admin Configuration

Category Mapping

The Category Mapping section allows you to map product categories to specific FFL firearm types using an improved tree-based multi-select UI.

This new interface makes it easier to:

  • Select multiple categories
  • Understand parent–child category relationships
  • Clearly see selected categories as removable tags (chips)

Note: If a product has attributes set, those override the category-level settings.

Product Mapping

FFL Mapping

  • Custom Attribute Name:
    Enter the product custom attribute that determines if an item is FFL or not (e.g., FFL).
  • Custom Attribute Value:
    Enter the attribute value used to identify FFL items (e.g., YES).

FFL Firearm Type Mapping

  • Custom Attribute Name:
    Enter the custom attribute name used to classify firearm types (e.g., FFL_FIREARM_TYPE).

FFL Firearm Type Values Mapping

Map the custom attribute values to human-readable labels. These are typically synced with external systems like FFL360:

  • Hand Gun (Pistol or Revolver)
  • Long Gun (Rifle or Shotgun)
  • Other Firearm (Frame, Receiver, etc)
  • NFA

State Restriction

Direct Products To Dealer By State

  • This feature allows you to route Ammo, Barrels, and Firearm Parts through an FFL dealer for specific regions, based on configurable settings.

State restriction UI Text - Before and After

  • State Restriction UI Text will be displayed only when the cart contains Ammo, Barrel, or Firearm Parts products (with or without Non-FFL products) and does not contain Handgun, Long Gun, Other Firearms, or Suppressor (NFA) items.
  • When the cart includes Ammo / Barrel / Firearm Parts (with or without Non-FFL products), the “State Restriction UI Text” will be shown on the checkout page for the first time.
  • If the customer first enters a ZIP code that does not require FFL dealer checkout and the shipping address is shown, but then updates the ZIP code to one that belongs to a restricted state, the “State Restriction UI Text After” content will be displayed on the checkout UI.

Blocked Products by State

Enable/Disable State Restriction

  • Yes – Enables state-level restrictions for FFL checkout.
  • No – Disables the restrictions; all customers can proceed with checkout regardless of state.

State Restriction Rules

  • Implemented advanced state-based checkout restriction that blocks the entire checkout process when cart contains restricted SKUs for configured states; supports multiple rules with state and SKU mapping, validating the customer’s entered ZIP code against restricted states and automatically preventing checkout if a match is found.

Restricted States

  • Purpose: Select one or more U.S. states where FFL item shipping is not allowed.
  • Customers with shipping addresses in these states will not be allowed to complete checkout for FFL items.

State Restriction Message

  • Purpose: Customize the error message shown to users trying to purchase FFL items from restricted states.
    • Example Message: Sorry, we cannot ship firearms to your state due to local regulations.

Advanced Configuration

Environment Setting

Local (Development) Environment?
Select whether the current environment is a local development setup. Choose:

  • Yes – If you’re working in a local or staging environment.
  • No – For live production websites.

Enable/Disable - I am an FFL / B2B Order flow.

  • You can enable or disable the B2B flow from this setting. When enabled, B2B users can enter their FFL license number directly on the checkout UI.
  • In this flow, users are not required to enter a ZIP code or search for an FFL dealer. Instead, they simply enter their FFL license number and proceed to place the order using their preferred or mailing address.

Order Status Mapping

Choose the WooCommerce order status that should be mapped for FFL360 order syncing (e.g., Processing).

FFL Checkout – Exclude Specific User Roles

  • Exclude User Roles:
    Select user roles (e.g., Administrator, Editor) that should bypass the FFL dealer selection process during checkout.

Settings

FFL Select UI Color Settings

This section allows you to customize the appearance of the FFL Dealer selection UI.

  • Header Color: Applied to the header/title section of the FFL selection modal or UI block.
  • Button Color: Applied to the Select buttons within the FFL UI.

FFL Checkout UI Text Settings

FFL Checkout UI Text Configuration allows you to customize the text and button styles displayed during the firearm checkout process, ensuring a seamless customer experience.

  • Heading Text: Message displayed at the top of the FFL selection section to guide users through selecting a dealer.
  • Choose Dealer Button Label: The text shown on the button customers click to select their FFL dealer.
  • Choose Dealer Button Text Color: Sets the color of the text inside the "Choose Dealer" button for better visibility or branding.
  • Choose Dealer Button Background Color: Defines the background color of the "Choose Dealer" button to match store design.
  • Terms Text: Legal or informational message confirming the customer’s understanding and responsibility regarding FFL shipment and coordination.

Configure FFL Fields for a Product

  • Set Product as FFL: Yes / No.
  • Set Firearm Type: Select from product configuration.

Frontend Checkout View

FFL Dealer UI on checkout

  • During checkout, the customer will enter the postal code.
  • A list of available FFL dealers will be displayed for selection.

FFL Dealer Selection UI

  • Customers can choose the dealer near them and proceed to checkout.

Selected Dealer information

  • Once selected, the dealer’s information will automatically appear on the checkout page

Ammo / Barrels / Firearm Part only in cart

  • When the cart contains Ammo, Barrels, or Firearm Parts (with or without Non-FFL items) and does not contain Handgun, Long Gun, Other Firearms, or Suppressor (NFA) items, the checkout UI will appear as described above.
    • The checkout UI content is fully configurable, as outlined earlier. Based on the ZIP code entered:
      • If the ZIP code belongs to a restricted state, the system will open the FFL dealer selection popup.
      • If the ZIP code does not belong to a restricted state, the system will display the default shipping address form.
      • If the customer re-enters a restricted ZIP code in the shipping address, the checkout UI will be displayed with the “State Restriction UI Text – After” content, as shown below.

B2B Flow enabled - Checkout UI

When the B2B flow is enabled, the checkout displays tabs that allow the user to either enter a ZIP code or select “I AM AN FFL” to proceed.

B2B Flow enabled - I AM AN FFL TAB

  • This allows users to enter their FFL license number (full or abbreviated). If the license number is valid, the system will display the dealer address, allowing the user to select it and proceed with placing the order.

FFL Master Proof in Order view

  • Once a customer selects an FFL dealer during checkout, the dealer’s details are saved with the order. As an administrator, you can easily view this information in the Order Details page inside the admin panel.
  • From the order view, administrators can download the Transfer Proof document directly using the provided link.

FFL Master Proof

When the transferURL is ready from the FFL360 system, the following API is triggered:

  • URL: {Base URL}/wp-json/wp/v2/add-ffl-url
  • Method: POST

Request Payload Example

{
  "storeDomain": "storedomain.com",
  "orderId": "4657",
  "order_note": "www.transferproofurl.com",
  "dealerId": "8-23-091-07-8D-15050",
  "premiseAddress": {
      "street": "846 ELLIS STREET",
      "city": "ROSWELL",
      "state": "GA",
      "zipCode": "30075"
  },
  "tradeName": "CHATTAHOOCHEE MUNITIONS, LLC"
}

Functionality

This API updates the order's:

  • Shipping address with the selected FFL dealer's address.
  • FFL License Number
  • Master Transfer Proof (as part of the dealer data).

Dealer Reassign

If the dealer is changed after the order is placed, this same API is triggered again. It updates the order with the new dealer's:

  • Shipping Address
  • Transfer URL
  • FFL License Number

This ensures the order details always reflect the latest selected dealer.

Support Required

For assistance, contact our dedicated support team:

Updated 3 months ago

Did this page help you?