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. Listings missing any of these fields will not import.
| 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. |
Optional Fields
These fields enrich your listing but aren't required. We recommend including them whenever possible.
| Field | Type | Constraints | Description |
|---|---|---|---|
shipping_info | text | max 60 chars | Free-text shipping details shown on the listing (e.g. "Free shipping", "Flat $9.95", "$5 / free over $99"). Optional. |
in_stock | boolean | 1/0 or true/false | Whether the listing is currently available. Defaults to truthy if omitted or the value is ambiguous. |
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. |
Legacy shipping fields are still accepted: free_shipping, shipping_cost, and aliases such as shipping, shippingPrice, shippingFee, deliveryFee are automatically folded into shipping_info on import, so existing feeds keep working. shipping_info is the current field — prefer it in new feeds.
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 | Recommended | Cartridge / shotshell gauge. | 9mm Luger, .223 Rem, 12 gauge |
ammo.rounds | Recommended | Number of rounds in this offer. Must be a positive integer if provided. | 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 ammo subfields are recommended — fill in what you know and skip what you don't, and the listing still imports. The only hard requirement is case_material when fire_type=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 | Recommended | 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 | Recommended | One of: bullet, brass, primer. | bullet |
reloading.rounds | Recommended | Round count. Must be a positive integer if provided. | 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 | Recommended | 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 | Recommended | 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>
<shipping_info>Flat $15.00</shipping_info>
<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>
<shipping_info>Free shipping</shipping_info>
<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>
<shipping_info>Flat $9.95</shipping_info>
<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>
<shipping_info>$7.50 flat</shipping_info>
<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>
<shipping_info>Free shipping</shipping_info>
<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>
<shipping_info>Flat $12.00</shipping_info>
<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>
<shipping_info>Free shipping</shipping_info>
<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>
<shipping_info>Flat $5.99</shipping_info>
<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",
"shipping_info": "Flat $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",
"shipping_info": "Free shipping",
"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",
"shipping_info": "Flat $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",
"shipping_info": "$7.50 flat",
"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",
"shipping_info": "Free shipping",
"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",
"shipping_info": "Flat $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",
"shipping_info": "Free shipping",
"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",
"shipping_info": "Flat $5.99",
"in_stock": true
}
]
}
upc,sku,name,brand,category,price,map_price,condition,url,shipping_info,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,"Flat $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,"Free shipping",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,"Flat $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,"$7.50 flat",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,"Free shipping",0,,,,,,,,,,,,,,,,,,,, 662410500358,,"Hornady XTP 9mm 115gr Bullets, 100ct",Hornady,reloading,54.99,,new,https://example-dealer.com/p/hornady-xtp-9mm,"Flat $12.00",1,,,,,,,,,,,bullet,100,.355,,,,,,, 610953154295,,"Benchmade Bugout 535",Benchmade,knife,165.00,,new,https://example-dealer.com/p/benchmade-535,"Free shipping",1,,,,,,,,,,,,,,,,,,,folding,3.24,S30V 889912345678,,"Vortex Logo T-Shirt, Black, XL",Vortex,apparel,24.99,,new,https://example-dealer.com/p/vortex-tshirt,"Flat $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.
Category subfieldsMost category subfields (ammo.caliber, ammo.rounds, part.type, reloading.type, reloading.rounds, optic.type, knife.type) are recommended and produce warnings if missing — the listing still imports. Hard requirements:
ammo.case_material when fire_type=centerfire, and reloading.bullet_caliber / brass_cartridge / primer_size when the matching reloading.type is set. Where positive-integer counts are provided (ammo.rounds, reloading.rounds), non-integer values are rejected.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