DOCUMENTATION
Dealer Feed Schema v1.1
The official spec for syncing your inventory with GunRack. Format your feed as XML, JSON, or CSV; host it at a public URL; we import on a schedule based on your subscription tier.
Overview
Your feed is a flat list of listings. Each listing represents one product you have in stock and contains the fields described in this document. Listings are not nested by category — everything sits at the top level. Category-specific fields (like ammo.caliber or firearm.model) are grouped under their own sub-block in XML and JSON, or appear as flat dotted columns in CSV.
All three formats produce identical data after parsing. Pick whichever is easier for your existing system to generate.
What our importer expects:
- A publicly reachable HTTPS URL (Basic Auth or API key headers supported)
- A feed body in XML, JSON, or CSV format
- Same content on every request — no per-request pagination or filtering
- Updated at least once per day
Required Fields
Every listing must include all of these, regardless of category.
| Field | Type | Constraints | Description |
|---|---|---|---|
upc | string | 12 or 13 digits | UPC-A or EAN-13 barcode. Dashes/spaces are stripped automatically. |
category | enum | see below | One of: firearm, ammo, part, accessory, optic, reloading, knife, apparel. |
price | decimal | greater than 0 | Your selling price in USD. No currency symbol. |
condition | enum | see below | One of: new, used, refurbished. |
url | URL | https:// | Direct link to the product page on your site. |
free_shipping | boolean | 1/0 or true/false | Whether shipping is included in the price. |
shipping_cost | decimal | greater than or equal to 0 | Required when free_shipping is not 1. |
in_stock | boolean | 1/0 or true/false | Whether the listing is currently available for purchase. |
Optional Fields
These fields enrich your listing but aren't required. We recommend including them whenever possible.
| Field | Type | Constraints | Description |
|---|---|---|---|
sku | string | max 100 chars | Your internal SKU. Useful for reconciling listings with your inventory. |
map_price | decimal | greater than price | Manufacturer's MAP. When set, listing displays MAP and shows a "Click to see price" CTA pointing to your URL. |
stock_qty | integer | greater than or equal to 0 | Exact quantity on hand. Helps power low-stock alerts. |
name | string | max 200 chars | Concise product name. Helps when the UPC isn't in our master catalog yet. |
brand | string | max 100 chars | Manufacturer name (e.g. Federal, Glock, Vortex). |
mpn | string | max 100 chars | Manufacturer Part Number. Use the original MPN without prefixes. |
image_url | URL | https:// | Product image. JPEG, PNG, or WebP. |
Category-Specific Fields
Each category has its own set of fields that enable buyers to filter and search precisely. In XML and JSON, these are nested under a category-named block (e.g. <ammo><caliber>...</caliber></ammo>). In CSV, they're flat columns with dotted names (e.g. ammo.caliber).
Ammo category=ammo
| Field | Required | Description | Examples / Values |
|---|---|---|---|
ammo.caliber | Required | Cartridge / shotshell gauge. | 9mm Luger, .223 Rem, 12 gauge |
ammo.rounds | Required | Number of rounds in this offer (positive integer). | 50, 1000 |
ammo.fire_type | Optional | Primer/fire mechanism type. | centerfire, rimfire, black_powder, shotgun |
ammo.bullet_design | Optional | Bullet construction. FMJ for training, hollow point or soft point for self-defense, polymer tip for hunting. | fmj, hollow_point, soft_point, polymer_tip, frangible, aluminum_tip |
ammo.tip_color | Optional | Visible tip color marking. Common in military-grade and specialty ammo (e.g. green tip M855 has a steel core, red is a tracer). | green, red, orange, black, blue, silver, white |
ammo.case_material | Required if fire_type=centerfire | Cartridge case material. Steel-cased ammo is cheaper but causes more wear. | brass, steel, aluminum, nickel |
All fields beyond caliber and rounds are optional — fill in what you know and skip what you don't. The case_material field is required only when fire_type is centerfire (rimfire, shotgun, and black powder rounds use varied/non-standard cases).
Firearm category=firearm
| Field | Required | Description | Examples |
|---|---|---|---|
firearm.model | Recommended | General model name. Not the full SKU. | Glock 19, AR-15, Sig P320 |
firearm.type | Optional | Firearm type. | handgun, rifle, shotgun, revolver |
firearm.action | Optional | Action type. | semi-auto, bolt-action, single-action |
firearm.caliber | Optional | Firearm caliber. | 9mm Luger, .308 Win |
All firearm subfields are technically optional, but listings with no firearm.model, firearm.type, or firearm.caliber won't appear in firearm-specific search filters.
Part category=part
| Field | Required | Description | Examples |
|---|---|---|---|
part.type | Required | Precise part category. Not too vague, not too detailed. | 1911 magazine, AR-15 lower, AR-10 charging handle |
Reloading category=reloading
| Field | Required | Description | Examples |
|---|---|---|---|
reloading.type | Required | One of: bullet, brass, primer. | bullet |
reloading.rounds | Required | Positive integer count. | 100, 1000 |
reloading.bullet_caliber | Required if type=bullet | Bullet diameter or caliber. | .355, 9mm |
reloading.brass_cartridge | Required if type=brass | Brass cartridge name. | 9mm Luger |
reloading.primer_size | Required if type=primer | Primer size. | small pistol, large rifle |
Optic category=optic
| Field | Required | Description | Examples |
|---|---|---|---|
optic.type | Required | One of: red_dot, holographic, lpvo, rifle_scope, pistol_scope, magnifier, iron_sights, prism. | lpvo |
optic.magnification | Optional | Magnification range. | 1x, 4-16x, 1-6x |
optic.reticle | Optional | Reticle style. | MOA, MIL, BDC, dot |
optic.objective_mm | Optional | Objective lens diameter in mm (integer). | 24, 50 |
Knife category=knife
| Field | Required | Description | Examples |
|---|---|---|---|
knife.type | Required | One of: fixed_blade, folding, automatic, assisted, multitool. | folding |
knife.blade_length_in | Optional | Blade length in inches (decimal). | 3.24, 4.5 |
knife.blade_steel | Optional | Blade steel. | S30V, D2, 1095 |
Accessory and Apparel category=accessory or apparel
No category-specific required fields. Catch-all categories for products that don't fit elsewhere (slings, cases, holsters, t-shirts, hats, etc.).
Format Examples
The same 8 listings (one per category) shown in all three formats. The ammo listing demonstrates the new optional subfields (fire_type, bullet_design, case_material). Pick whichever format your system can generate most easily.
<?xml version="1.0" encoding="UTF-8"?>
<gunrack_feed xmlns="https://gunrack.deals/schema/feed/v1.1" version="1.1">
<listings>
<listing>
<upc>764503913051</upc>
<sku>GLK-19-G5-MOS</sku>
<name>Glock 19 Gen5 MOS 9mm 4.02"</name>
<brand>Glock</brand>
<category>firearm</category>
<price>549.99</price>
<map_price>619.99</map_price>
<condition>new</condition>
<url>https://example-dealer.com/p/glock-19-gen5-mos</url>
<free_shipping>0</free_shipping>
<shipping_cost>15.00</shipping_cost>
<in_stock>1</in_stock>
<stock_qty>3</stock_qty>
<firearm>
<model>Glock 19</model>
<type>handgun</type>
<action>semi-auto</action>
<caliber>9mm Luger</caliber>
</firearm>
</listing>
<listing>
<upc>076683081124</upc>
<name>Federal Champion 9mm 115gr FMJ 50rd</name>
<brand>Federal</brand>
<category>ammo</category>
<price>22.99</price>
<condition>new</condition>
<url>https://example-dealer.com/p/federal-9mm-50ct</url>
<free_shipping>1</free_shipping>
<in_stock>1</in_stock>
<stock_qty>120</stock_qty>
<ammo>
<caliber>9mm Luger</caliber>
<rounds>50</rounds>
<fire_type>centerfire</fire_type>
<bullet_design>fmj</bullet_design>
<case_material>brass</case_material>
</ammo>
</listing>
<listing>
<upc>610563272730</upc>
<name>Vortex Viper PST Gen II 1-6x24 SFP</name>
<brand>Vortex</brand>
<category>optic</category>
<price>449.00</price>
<condition>new</condition>
<url>https://example-dealer.com/p/vortex-viper-pst</url>
<free_shipping>0</free_shipping>
<shipping_cost>9.95</shipping_cost>
<in_stock>1</in_stock>
<optic>
<type>lpvo</type>
<magnification>1-6x</magnification>
<reticle>MOA</reticle>
<objective_mm>24</objective_mm>
</optic>
</listing>
<listing>
<upc>851561006033</upc>
<name>Used AR-15 Bolt Carrier Group, M16 profile</name>
<category>part</category>
<price>89.99</price>
<condition>used</condition>
<url>https://example-dealer.com/p/used-ar15-bcg</url>
<free_shipping>0</free_shipping>
<shipping_cost>7.50</shipping_cost>
<in_stock>1</in_stock>
<part>
<type>AR-15 bolt carrier group</type>
</part>
</listing>
<listing>
<upc>699618782301</upc>
<name>Magpul PMAG 30 AR/M4 GEN M3</name>
<brand>Magpul</brand>
<category>accessory</category>
<price>14.99</price>
<condition>new</condition>
<url>https://example-dealer.com/p/magpul-pmag-30</url>
<free_shipping>1</free_shipping>
<in_stock>0</in_stock>
</listing>
<listing>
<upc>662410500358</upc>
<name>Hornady XTP 9mm 115gr Bullets, 100ct</name>
<brand>Hornady</brand>
<category>reloading</category>
<price>54.99</price>
<condition>new</condition>
<url>https://example-dealer.com/p/hornady-xtp-9mm</url>
<free_shipping>0</free_shipping>
<shipping_cost>12.00</shipping_cost>
<in_stock>1</in_stock>
<reloading>
<type>bullet</type>
<rounds>100</rounds>
<bullet_caliber>.355</bullet_caliber>
</reloading>
</listing>
<listing>
<upc>610953154295</upc>
<name>Benchmade Bugout 535</name>
<brand>Benchmade</brand>
<category>knife</category>
<price>165.00</price>
<condition>new</condition>
<url>https://example-dealer.com/p/benchmade-535</url>
<free_shipping>1</free_shipping>
<in_stock>1</in_stock>
<knife>
<type>folding</type>
<blade_length_in>3.24</blade_length_in>
<blade_steel>S30V</blade_steel>
</knife>
</listing>
<listing>
<upc>889912345678</upc>
<name>Vortex Logo T-Shirt, Black, XL</name>
<brand>Vortex</brand>
<category>apparel</category>
<price>24.99</price>
<condition>new</condition>
<url>https://example-dealer.com/p/vortex-tshirt</url>
<free_shipping>0</free_shipping>
<shipping_cost>5.99</shipping_cost>
<in_stock>1</in_stock>
</listing>
</listings>
</gunrack_feed>
{
"listings": [
{
"upc": "764503913051",
"sku": "GLK-19-G5-MOS",
"name": "Glock 19 Gen5 MOS 9mm 4.02\"",
"brand": "Glock",
"category": "firearm",
"price": 549.99,
"map_price": 619.99,
"condition": "new",
"url": "https://example-dealer.com/p/glock-19-gen5-mos",
"free_shipping": false,
"shipping_cost": 15.00,
"in_stock": true,
"stock_qty": 3,
"firearm": {
"model": "Glock 19",
"type": "handgun",
"action": "semi-auto",
"caliber": "9mm Luger"
}
},
{
"upc": "076683081124",
"name": "Federal Champion 9mm 115gr FMJ 50rd",
"brand": "Federal",
"category": "ammo",
"price": 22.99,
"condition": "new",
"url": "https://example-dealer.com/p/federal-9mm-50ct",
"free_shipping": true,
"in_stock": true,
"stock_qty": 120,
"ammo": {
"caliber": "9mm Luger",
"rounds": 50,
"fire_type": "centerfire",
"bullet_design": "fmj",
"case_material": "brass"
}
},
{
"upc": "610563272730",
"name": "Vortex Viper PST Gen II 1-6x24 SFP",
"brand": "Vortex",
"category": "optic",
"price": 449.00,
"condition": "new",
"url": "https://example-dealer.com/p/vortex-viper-pst",
"free_shipping": false,
"shipping_cost": 9.95,
"in_stock": true,
"optic": {
"type": "lpvo",
"magnification": "1-6x",
"reticle": "MOA",
"objective_mm": 24
}
},
{
"upc": "851561006033",
"name": "Used AR-15 Bolt Carrier Group, M16 profile",
"category": "part",
"price": 89.99,
"condition": "used",
"url": "https://example-dealer.com/p/used-ar15-bcg",
"free_shipping": false,
"shipping_cost": 7.50,
"in_stock": true,
"part": { "type": "AR-15 bolt carrier group" }
},
{
"upc": "699618782301",
"name": "Magpul PMAG 30 AR/M4 GEN M3",
"brand": "Magpul",
"category": "accessory",
"price": 14.99,
"condition": "new",
"url": "https://example-dealer.com/p/magpul-pmag-30",
"free_shipping": true,
"in_stock": false
},
{
"upc": "662410500358",
"name": "Hornady XTP 9mm 115gr Bullets, 100ct",
"brand": "Hornady",
"category": "reloading",
"price": 54.99,
"condition": "new",
"url": "https://example-dealer.com/p/hornady-xtp-9mm",
"free_shipping": false,
"shipping_cost": 12.00,
"in_stock": true,
"reloading": { "type": "bullet", "rounds": 100, "bullet_caliber": ".355" }
},
{
"upc": "610953154295",
"name": "Benchmade Bugout 535",
"brand": "Benchmade",
"category": "knife",
"price": 165.00,
"condition": "new",
"url": "https://example-dealer.com/p/benchmade-535",
"free_shipping": true,
"in_stock": true,
"knife": { "type": "folding", "blade_length_in": 3.24, "blade_steel": "S30V" }
},
{
"upc": "889912345678",
"name": "Vortex Logo T-Shirt, Black, XL",
"brand": "Vortex",
"category": "apparel",
"price": 24.99,
"condition": "new",
"url": "https://example-dealer.com/p/vortex-tshirt",
"free_shipping": false,
"shipping_cost": 5.99,
"in_stock": true
}
]
}
upc,sku,name,brand,category,price,map_price,condition,url,free_shipping,shipping_cost,in_stock,stock_qty,ammo.caliber,ammo.rounds,ammo.fire_type,ammo.bullet_design,ammo.case_material,firearm.model,firearm.type,firearm.action,firearm.caliber,part.type,reloading.type,reloading.rounds,reloading.bullet_caliber,optic.type,optic.magnification,optic.reticle,optic.objective_mm,knife.type,knife.blade_length_in,knife.blade_steel 764503913051,GLK-19-G5-MOS,"Glock 19 Gen5 MOS 9mm",Glock,firearm,549.99,619.99,new,https://example-dealer.com/p/glock-19-gen5-mos,0,15.00,1,3,,,,,,Glock 19,handgun,semi-auto,9mm Luger,,,,,,,,,,, 076683081124,,"Federal Champion 9mm 115gr FMJ 50rd",Federal,ammo,22.99,,new,https://example-dealer.com/p/federal-9mm-50ct,1,,1,120,9mm Luger,50,centerfire,fmj,brass,,,,,,,,,,,,,, 610563272730,,"Vortex Viper PST Gen II 1-6x24",Vortex,optic,449.00,,new,https://example-dealer.com/p/vortex-viper-pst,0,9.95,1,,,,,,,,,,,,,,,,lpvo,1-6x,MOA,24,,, 851561006033,,"Used AR-15 Bolt Carrier Group",,part,89.99,,used,https://example-dealer.com/p/used-ar15-bcg,0,7.50,1,,,,,,,,,,AR-15 bolt carrier group,,,,,,,,,, 699618782301,,"Magpul PMAG 30 AR/M4 GEN M3",Magpul,accessory,14.99,,new,https://example-dealer.com/p/magpul-pmag-30,1,,0,,,,,,,,,,,,,,,,,,,, 662410500358,,"Hornady XTP 9mm 115gr Bullets, 100ct",Hornady,reloading,54.99,,new,https://example-dealer.com/p/hornady-xtp-9mm,0,12.00,1,,,,,,,,,,,bullet,100,.355,,,,,,, 610953154295,,"Benchmade Bugout 535",Benchmade,knife,165.00,,new,https://example-dealer.com/p/benchmade-535,1,,1,,,,,,,,,,,,,,,,,,,folding,3.24,S30V 889912345678,,"Vortex Logo T-Shirt, Black, XL",Vortex,apparel,24.99,,new,https://example-dealer.com/p/vortex-tshirt,0,5.99,1,,,,,,,,,,,,,,,,,,,
Validation Rules
Before pointing the importer at a live feed, dealers can paste a sample at our validator and get a per-row report. The validator parses the feed exactly the way the importer does, runs every check listed below, and returns errors (block import) and warnings (allowed but flagged).
UPC formatMust be 12 or 13 digits. Non-digit characters get stripped with a warning.
UPC duplicatesSame UPC appearing more than once in one feed produces a warning. Last occurrence wins on import.
Price greater than 0Prices of 0 or negative are rejected. Prices over $100,000 produce a warning.
MAP greater than priceWhen map_price is set, it must exceed price. Otherwise MAP is ignored on import.
URL https onlyhttp:// URLs are rejected. Mixed-content image URLs trigger a warning.
Category enumMust be exactly one of the 8 allowed values. Case-insensitive.
Condition enumMust be new, used, or refurbished. Case-insensitive.
Shipping conditionalshipping_cost is required unless free_shipping is 1.
Category subfieldsammo.caliber/rounds, part.type, reloading.type/rounds + type-specific subfield, optic.type, knife.type all required when category matches.
Ammo enumsfire_type, bullet_design, tip_color, case_material all enforce their valid value lists. case_material is required when fire_type=centerfire.
Field lengthname 200 chars, brand/mpn/sku 100 chars. Over-length values trigger warnings (or errors for sku).
Test your feed
Subscribed dealers can paste a feed sample at the validator and get a real-time validation report. The validator runs the same checks the importer does — if it passes the validator, it'll pass the importer.
Open Validator Become a Dealer