GunBroker Connector¶

Manage GunBroker sales and inventory directly from Odoo -- listing creation, order fulfillment, inventory synchronization, and compliance tracking in a single integration.


Module	`gunbroker`
Version	18.0.1.1.0
Category	Sales
License	LGPL-3
Author	Longhorn Web Solutions

Overview¶

The GunBroker Connector integrates GunBroker's marketplace API with Odoo 18, enabling firearms dealers and accessory retailers to manage their entire GunBroker operations from within Odoo. The module handles the complete product lifecycle from listing creation through order fulfillment, with automated inventory synchronization and FFL compliance tracking.

Key capabilities:

Create, update, and end listings on GunBroker from Odoo
Import orders with automatic customer and address creation
Synchronize inventory quantities and prices in real time
Submit tracking numbers and mark orders as shipped
Manage premium listing features with cost tracking
Support for both fixed-price and auction listing types

Installation & Dependencies¶

Odoo Module Dependencies¶

base
sale_management
stock

Python Dependencies¶

requests
requests_toolbelt

Prerequisites¶

Odoo 18.0 Community or Enterprise
An active GunBroker developer account
GunBroker API credentials (username, password, developer key)

Installation Steps¶

Place the gunbroker module directory in your Odoo addons path.
Restart the Odoo service.
Navigate to Apps, remove the "Apps" filter, search for "GunBroker", and click Install.

Configuration¶

Creating a GunBroker Instance¶

Navigate to the GunBroker menu and open Configuration > Instance.

Click Create to add a new instance.
Fill in the required fields:

Field	Description
Name	A descriptive label for this connection (e.g., "Production Store")
Username	Your GunBroker account username
Password	Your GunBroker account password
Dev Key	Your GunBroker developer key
Environment	Select Sandbox for testing or Production for live operations
Company	The Odoo company associated with this instance

Click Test Connection to validate credentials. A success notification confirms the connection, and the status changes to Confirmed.

Always Test in Sandbox First

Before configuring a production instance, create a sandbox instance and verify all operations (listing, orders, stock sync) work correctly. The sandbox environment uses api.sandbox.gunbroker.com while production uses api.gunbroker.com.

API Credentials¶

The module uses the GunBroker API v1. Authentication is handled via an access token that is automatically generated when you test the connection and refreshed every 30 minutes by a scheduled action.

Environment	API Base URL
Sandbox	`https://api.sandbox.gunbroker.com`
Production	`https://api.gunbroker.com`

The API URL is automatically set based on your environment selection -- no manual entry is required.

Instance Defaults¶

The instance record serves as the central configuration hub. Settings configured here are automatically applied as defaults when enabling GunBroker on a product.

Order ProcessingListing DefaultsShipping DefaultsAutomation & Inventory

Setting	Description
Auto-Confirm Orders	Automatically confirm imported sales orders
Auto-Process Orders	Confirm orders, create invoices, and process payments automatically
Payment Journal	Bank or cash journal for automatic payment processing
Warehouse	Default warehouse for inventory management
Fiscal Position	Tax mapping for GunBroker sales
Taxes	Default taxes applied to GunBroker orders

Setting	Description
Default Listing Type	Fixed Price or Auction
Fixed Price Duration	30, 60, or 90 days
Auction Duration	1 to 14 days
Default Condition	Factory New, New Old Stock, or Used
Default Inspection Period	Return policy (14 options from "AS IS" to 30-day guarantee)
Default FFL Required	Whether products require an FFL by default
Default Weight Unit	Pounds or Kilograms

Setting	Description
Who Pays for Shipping	See item description, Seller pays, Buyer pays actual, Buyer pays fixed, or Use shipping profile
Will Ship International	Enable international shipping
Default Shipping Profile	Pre-configured shipping profile
Default Carrier	FedEx, UPS, or USPS (used for tracking submission)

Setting	Description
Max Display Quantity	Cap the quantity shown on GunBroker (0 = show actual). Useful to avoid revealing total inventory
Custom Image Domain	CDN domain for product image URLs (e.g., `https://cdn.yourstore.com`)
Import Page Sizes	Products, orders, and categories per API call (default: 100)

Listing Management¶

Enabling GunBroker on a Product¶

Open a product in Sales > Products.
Navigate to the GunBroker tab.
Check Sell on GunBroker -- this automatically populates defaults from the instance configuration.

Product Fields¶

When "Sell on GunBroker" is enabled, the following fields become available:

Basic InformationPricingListing Options

Field	Description
GunBroker Title	Marketplace-specific title (max 75 characters). Falls back to product name if empty
GB Category	GunBroker category (only leaf categories can be assigned)
Condition	Factory New, New Old Stock, or Used
FFL Required	Whether the item requires an FFL dealer for shipping
Standard Text	Reusable content block appended to the listing
Description Header/Body/Footer	Rich HTML description sections

Fixed Price listings:

Field	Description
GunBroker Price	The fixed sale price
Accept Offers	Allow buyers to submit offers
Auto Accept Price	Automatically accept offers at or above this amount
Auto Reject Price	Automatically reject offers at or below this amount

Auction listings:

Field	Description
Starting Bid	Opening bid price
Buy Now Price	Optional immediate purchase price (must exceed starting bid)
Reserve Price	Minimum sale price (not allowed for 1- and 3-day auctions)

Field	Description
Listing Type	Fixed Price or Auction
Duration	Fixed Price: 30/60/90 days. Auction: 1-14 days
Auto Relist	Fixed Price: on/off. Auction: Do Not Relist, Relist Until Sold, or Relist Fixed Count

Creating a Listing¶

After configuring the product fields, click List on GunBroker from the product form. The module validates the product data, builds the API payload, and creates the listing.

On success:

The Listing ID is stored on the product
The Listing Date is recorded
The GunBroker URL is computed and links directly to the live listing

Validation Rules

The module enforces GunBroker's business rules before creating a listing:

SKU (default_code) is required
A GunBroker description is required
A leaf category must be selected
Buy Now price must exceed Starting Bid for auctions
Reserve price must be between Starting Bid and Buy Now
Reserve price and auto-relist are not allowed for 1- and 3-day auctions
At least one shipping class must be selected when buyer pays shipping

Updating a Listing¶

Click Update on GunBroker from the product form to push changes (title, description, pricing, shipping, premium features) to an active listing.

Zero Quantity Protection

The module prevents updating a listing to zero quantity. Items with zero stock must be ended (delisted) instead. This avoids GunBroker's minimum-quantity behavior that could set quantity to 1.

Ending a Listing¶

Click End Listing on GunBroker to remove the listing from GunBroker. This clears the Listing ID and resets the product's GunBroker status in Odoo.

Note

You cannot uncheck "Sell on GunBroker" while a listing is active. End the listing first, then disable the flag.

Relisted Item Detection¶

When updating a listing, if GunBroker returns a 403 error indicating the item has bids, the module automatically checks whether the item was relisted under a new ID. If a new listing ID is found, the product record is updated and the operation is retried.

Premium Listing Features¶

Premium features boost listing visibility on GunBroker. Each feature has an associated per-listing fee.

Feature	Cost	Description
View Counter	$0.50	Displays a view count on the listing
Featured Item	$2.95	Boosts visibility in search results
Highlighted Listing	$2.00	Colored background in search results
Showcase Item	$4.95	Premium placement in showcase sections
Bold Title	$1.00	Bold formatting for the listing title
Title Color	$1.00	Red, Green, or Blue title text
Subtitle	$3.50	Additional 50-character descriptive text
Sponsored Onsite	$4.00	Enhanced onsite promotion
Sponsored Offsite	$7.00	Enhanced offsite promotion
Scheduled Start	--	Schedule listing activation for a future date/time

The Total Premium Cost and Cost Breakdown fields on the product form calculate the combined fee for all enabled features.

Shipping Configuration¶

Shipping Methods¶

The module supports two shipping configuration approaches:

Shipping ProfilesShipping Classes

Shipping profiles are pre-configured shipping templates imported from your GunBroker account. Select "Use shipping profile" as the shipping payment method, then choose a profile from the dropdown.

Profiles are imported via GunBroker > Operations > Import Shipping Profiles.

When the buyer pays for shipping (actual cost or fixed amount), you must select at least one shipping class:

Class	Description
Overnight	Next-day delivery
Two Day	2-day delivery
Three Day	3-day delivery
Ground	Standard ground shipping
First Class	USPS First Class
Priority	USPS Priority Mail
In-Store Pickup	Customer picks up at your location
Alaska/Hawaii	Special rates for AK/HI
Other	Other shipping methods

When Buyer Pays Fixed Amount is selected, you can also specify the cost for each enabled shipping class.

Shipping Payment Options¶

Option	Description
See item description	Shipping details described in listing text
Seller pays for shipping	Free shipping for the buyer
Buyer pays actual shipping cost	Calculated at checkout using selected shipping classes
Buyer pays fixed amount	Predetermined shipping costs per class
Use shipping profile	Uses a GunBroker shipping profile

Order Synchronization¶

Importing Orders¶

Orders can be imported manually or automatically.

Manual Import:

Navigate to GunBroker > Operations.
Select the instance(s) to import from.
Choose the Order Status filter (e.g., "Pending Shipment").
Select the Time Frame (24 hours to 90 days).
Click Import Sale Orders.

Automatic Import:

Enable Auto Import Sale Order on the instance record. The scheduled action runs daily and imports orders with status "Pending Shipment" (status code 4).

What Gets Created¶

For each imported order, the module creates:

Sale Order with the GunBroker order ID stored as reference
Customer (res.partner) with the buyer's GunBroker User ID -- existing customers are matched and reused
Shipping Address as a child contact of the customer
Order Lines with matched products (by SKU) or newly created products

Order Processing Pipeline¶

Depending on your instance configuration:

Setting	Behavior
Manual (default)	Orders are created as draft quotations
Auto-Confirm	Orders are automatically confirmed
Auto-Process	Orders are confirmed, invoiced, and payment is recorded in the configured journal

Order Fields¶

The following GunBroker-specific fields are tracked on each sale order:

Field	Description
GunBroker Instance	The instance this order was imported from
GunBroker Order ID	The original GunBroker order number
GB Order Date	When the order was placed on GunBroker
GB Payment Date	When payment was received
Tracking Submitted	Whether tracking has been sent to GunBroker
Tracking Status	Pending, Success, Failed, or Retry Required

Inventory Management¶

Stock Synchronization¶

The module keeps GunBroker listing quantities in sync with Odoo inventory.

How it works:

The cron job runs every 15 minutes (when enabled).
For each product with an active GunBroker listing, the module calculates: display_quantity = qty_available - outgoing_qty
If Max Display Quantity is configured on the instance and the actual quantity exceeds it, only the cap value is sent.
If the display quantity differs from what was last sent, the listing is updated via API.
If inventory reaches zero or below, the listing is automatically ended (not updated to zero).

Max Display Quantity

Setting a maximum display quantity is recommended for security. For example, if you have 500 units of an item but set Max Display Quantity to 10, GunBroker will only show "10 available." This prevents competitors from seeing your full inventory levels.

Automatic Delisting¶

When enabled, the Auto Delist Zero Quantity Items cron job ends listings for products that have reached zero inventory. This prevents overselling by removing the listing entirely rather than setting quantity to zero.

Listing Cleanup¶

The Auto Unlink Listing in Odoo cron job checks active GunBroker listings against the API. If a listing has ended on GunBroker (expired, sold, manually ended), the Odoo product is updated to clear the listing ID and status.

Tracking & Shipment¶

Submitting Tracking Numbers¶

Tracking numbers can be submitted to GunBroker either manually or automatically.

Manual Submission:

From a sale order with a completed delivery, click Submit Tracking to GunBroker. The module reads the tracking number from the most recent completed delivery and sends it to GunBroker along with the configured carrier.

Automatic Submission:

Enable Auto Submit Tracking Numbers on the instance. The scheduled action runs every 30 minutes and:

Finds all GunBroker orders with completed deliveries that have not yet had tracking submitted.
Extracts the tracking number from the delivery.
Submits the tracking number to GunBroker via the Orders API.
Marks the order as shipped on GunBroker.

Supported Carriers¶

Code	Carrier
1	FedEx
2	UPS
3	USPS

The default carrier is configured on the instance and used for all tracking submissions.

Payment Methods¶

Payment methods are managed under GunBroker > Configuration > Payment Methods. These are shared across instances via a many-to-many relationship and are included in the product export payload.

Default payment methods are pre-loaded via module data and include options such as:

Visa / MasterCard / Discover / American Express
Money Order / Cashier's Check
Personal Check
See Item Description

Category Management¶

Importing Categories¶

GunBroker categories are imported from the Categories Hierarchy API endpoint. Navigate to GunBroker > Operations and click Import Categories.

Categories are:

Stored globally (shared across all instances)
Organized in a parent-child hierarchy with full path display names (e.g., "Firearms > Handguns > Semi-Auto Pistols")
Tagged with default FFL requirements (Required, Not Required, or No Default)
Only leaf categories (those without children) can be assigned to products

Standard Text¶

Standard Text records are reusable content blocks (terms, conditions, policies) that can be attached to listings. Import them via GunBroker > Operations > Import Standard Text, or create them manually.

Each Standard Text record stores:

A name for internal reference
The GunBroker Text ID (synced from API)
HTML content
The associated instance

Scheduled Actions¶

All scheduled actions are disabled by default and must be activated manually after configuration.

Cron Job	Interval	Description
Auto Generate Access Token	30 minutes	Refreshes the API access token for all confirmed instances
Auto Import Products	Weekly	Imports new products from GunBroker
Auto Import Sale Orders	Daily	Imports orders with "Pending Shipment" status
Auto Update Products Stock	15 minutes	Syncs inventory quantities from Odoo to GunBroker
Auto Delist the Item	30 minutes	Ends listings for products with zero inventory
Auto Unlink Listing in Odoo	30 minutes	Clears listing data for items no longer active on GunBroker
Auto Submit Tracking Numbers	30 minutes	Sends tracking numbers for completed deliveries

Enable Crons in Order

Enable the Auto Generate Access Token cron first, then the others. Without a valid token, other operations will fail with authentication errors.

Webhook¶

The module provides a webhook endpoint for receiving GunBroker notifications:

POST /gb/product_sold

This endpoint accepts POST requests with JSON payloads and logs the received data. CSRF protection is disabled for this endpoint to allow external calls from GunBroker.

Logging¶

All GunBroker operations are logged in the GunBroker Log Book accessible from the GunBroker menu.

Each log entry records:

Field	Description
Instance	Which instance the operation was performed on
Operation	Import, Export, or Update
Application	Product, Order, Stock & Price, Category, Shipping Profile, or Authentication
Status	Success, Warning, or Error
Records Processed / Success / Failed	Counts for batch operations
Processing Time	Duration of the operation
Log Lines	Detailed line-by-line results

Troubleshooting¶

Authentication Failures¶

Error: 401 Unauthorized

Cause: Access token has expired or credentials are incorrect.

Solution:

Verify your username, password, and developer key are correct.
Click Test Connection on the instance to generate a fresh token.
Ensure the Auto Generate Access Token cron is enabled and running every 30 minutes.

JSON Parsing Errors¶

Error: Unexpected character encountered while parsing value

Cause: Boolean values sent as Python objects instead of JSON strings.

Solution: This is an internal issue. If you encounter this after a module update, verify that boolean fields in the API payload use json.dumps() formatting. Contact support if the error persists.

Category Assignment Issues¶

Cannot assign category to product

Cause: Only leaf categories (those without child categories) can be assigned to products.

Solution: Import the full category hierarchy and select a category that does not have sub-categories. Parent categories are displayed in the hierarchy but cannot be selected.

Shipping Validation Errors¶

At least one shipping class must be selected

Cause: The shipping payment method requires shipping classes, but none are enabled.

Solution: When "Buyer Pays Actual Shipping Cost" or "Buyer Pays Fixed Amount" is selected, enable at least one shipping class (Ground, Priority, etc.) on the product.

Quantity Sync Issues¶

Quantity not updating on GunBroker

Possible causes:

Max Display Quantity: If the actual quantity has not crossed the threshold, no update is sent.
Warehouse mismatch: Ensure the instance warehouse matches where your inventory is tracked.
Cron not running: Verify the Auto Update Stock cron is enabled and active.
Zero quantity: Items at zero quantity are delisted, not updated.

Listing Update Fails with 403¶

Cannot edit an item that has bids

Cause: The auction item has received bids, or the item was relisted under a new ID.

Solution: The module automatically checks for relisted items and updates the listing ID. If the item genuinely has bids, it cannot be modified until the auction ends.