In order to list your products, AmmoSeek need a data feed (in XML or JSON format) which describes each in-stock product you have for sale.
A data feed is simply a text file that described each individual item's data. It should reside on a web
server where we can access it at any time. For example: http://yourdomain.com/xmlfeed.php
(for live feeds) or http://yourdomain.com/xmlfeed.xml
(for feeds generated at least every 5 minutes).
As you develop your feed, you can use our Feed Tester to verify
that things look correct.
The format of the data feed isn't as important as the data it contains. However, a feed in our
format will get your products added to our site very quickly, whereas other formats will
require some time for us to properly parse it.
To meet our requirements:
The feed must be real-time or updated at least every 5 minutes.
The feed should include only in-stock, ready-to-ship products, or clearly indicate whether the
product is in-stock or not by a field like <qty_available>72</qty_available> or
<availability>in stock</availability>. [exception]
Each record in the feed should contain an indicator of the product type the record contains.
Product types we support, as described below, are:
"ammunition" - only loaded ammo and blanks
"magazines" - only magazines (no parts, tools, or loaders of any kind: springs, base plates, followers, moon clips, speed loaders, etc)
"guns" - only fully-assembled firearms, minus muzzle loaders - no parts of any kind: uppers, lowers, grips, etc
"bullets" - projectiles for reloading ammunition
"brass" - for reloading ammunition
"primers" - for reloading ammunition
"powder" - for reloading ammunition (no muzzloading items)
"reloading_misc" - dies, presses, etc - only items used for reloading ammunition - not a catch-all category for other products
This indicator of product type can be omitted if you are only selling one product type and do not
plan to expand in the future.
Our system is designed to read in one feed per retailer. Therefore, if you are going to list multiple product types (e.g. ammunition, magazines, primers, etc), all products should appear in the same data feed (with the main different being the value of the <type> field indicating the product type).
When one exists, each product should include a UPC or MPN, either in the <upc> field or in
the product title (<title>) somewhere.
All items listed in the feed should be purchasable by the general public without qualification (i.e. no "membership" or any other purchase
required). If you do offer a lower price with a membership, the higher (non-member) price is what
should appear in the data feed.
The <brand> field should contain the brand name of the product. Often this is the name of the manufacturer.
If the ammo contains Federal Brass and Nosler bullets, but your company remanufactured/reloaded it, then the <brand> field should contain your company's name, or "factory reload".
In this day and age with companies buying out other companies, the best rule of thumb is to supply us with the <brand> name most prominently displayed on the box. This means that American Eagle ammo should be labeled as such, rather than 'Federal'. And Sellier and Bellow ammo should be labeled as such rather than Magtech. Blazer rather than CCI. Lawman rather than Speer. Frontier rather than Hornady. Etc, etc, etc.
Purchase limits (for ammo): if there
is a limit to the number of boxes that a customer can purchase, and the limit corresponds to less than 1000 rounds, the
XML record should include a <purchaselimit> field, containing an integer equal to the maximum
number of boxes one may purchase. (A <purchaselimit> of 0 (or absence of this field) would
indicate no limit). Alternatively, you can put "N box limit" in the product title (where N is the
maximum number of boxes one can purchase). Remember, this rule only applies to limits of less than 1,000 rounds where the limit is set by policy, not simply by a low supply in stock.
Minimum purchases (for ammo): if the
customer must purchase a minimum number of units, it's best to simply fill in the <numrounds>
and <price> fields with the total number of rounds and total price that constitutes the
minimum. For example if you have a 50rd box for $9.99 but you require a minimum purchase of 10
boxes, then the <numrounds> should be set to "500 and the <price> set to "99.90".
Alternatively, you can populate a <minpurchase> field with the minimum number of units (in
this case 10) and we'll do the math for you before posting the item to our listings. (In lieu of
using a <minpurchase> field, you can add "N box minimum" to the product title, where N is the
minimum number of boxes the customer must purchase).
Ammo condition: if the ammunition is
not considered 'factory new', the XML record should contain a field called <condition> which
would have a value of "remanufactured", "seconds" or "surplus" (typically for military surplus ammo). A
condition of "new" is assumed if not otherwise specified. Alternatively, the terms
'remanufactured', 'military surplus', or 'seconds' (or "blemished") can be added to the product <title>.
NOTE: For our purposes, the terms "reloaded" and "remanufactured" are synonymous.
Ammo casing: if the case is not made of brass, there should be a
<casing> field (valid values are 'aluminum', 'steel', 'brass', 'NAS3', or 'composite').
Alternatively, the words 'steel case' or 'aluminum case' can be added to the product <title>. Note that our system will assume that ammunition has a brass case unless your feed indicates otherwise.
Each record in the feed should contain, at minimum, the information listed in the tabs below for
each product type.
The feed will contain a list of records. Each record in the data feed will correspond to a single product in
your catalog, and will point directly to the product page where the product can be purchased. Each record
must contain at least the following: (shown for each product type we list)
indication of condition, if not new (e.g. remanufactured). See above.
product title
URL to the product page
price
bullet diameter - in <caliber> field or can be part of product title if clearly spelled out (e.g .243" diam.)
count (number of bullets for given price)
brand name
product title
URL to the product page
price
caliber (can be part of product title) matching one from this list (please choose just one caliber name)
count (number of casings)
brand name
product title
URL to the product page
price
count (number of primers for given price)
brand name
product title
URL to the product page
price
brand name
product title
URL to the product page
price
count (how many of the item for given price)
brand name
product title
URL to the product page
price
caliber (can be part of product title) matching one from this list (please choose just one caliber name)
count (number of mags for given price)
brand name
product title
URL to the product page
price
gun (handgun, rifle, shotgun)
caliber (can be part of product title) matching one from this list (please choose just one caliber name)
brand name
NOTE: We only list full-assembled guns. No gun parts, even if some government entity deems the part to be a 'firearm'.
If the record is missing any of these, it will be skipped over in processing (and the product
will be excluded from our site).
There are other items we need, but are not show-stoppers: UPC, number of grains,
and shot size and shell length (for shotgun ammo). Please bear in mind that the more specific you can be
with each product, the better chance that users entering specific search criteria will find your
products.
Also of critical importance is:
The feed should only contain in-stock items, or each record should have a field that shows whether the
item is in-stock or otherwise, so we can filter out the ones that are not in stock. ("In stock" means
that the customer can order the item immediately, and it will be ready for shipping within a reasonable
timeframe -- usually within a week at most.. This is opposed to "backordered", "backorderable", "delayed",
"temporarily unavailable", etc).
NOTE: We do make allowances for listing very large quantities of ammunition (e.g. a pallet) that requires additional time for shipping. For these to be listed on AmmoSeek.com, the product title should clearly state something along the lines of "Made to order; expect 4-6 weeks for shipping"
The feed should be updated in real-time (meaning that it pulls from your product inventory when we request the feed).
Or, if the feed is a flat file, it should be updated at least every 5 minutes -- and preferably more
often. A feed updated less often will not suffice because one of the biggest selling points of
AmmoSeek.com is that we only list in-stock products. And depending on your inventory and how quickly you
move items, we could potentially be listing items that are not in stock, an event that would disqualify
your feed. It's important that the information in your data feed match the information on your web
site at all times.
While we prefer that the data feed
be in our format (as described below), other feed formats (such as the one you'd get from Google Store) may
also suffice, as long as the requirements listed above are met.
XML Examples
Here are XML examples for each of the types of products we list:
brass, steel, aluminum, NAS3, composite (consider base metal only, ignoring any plating)
Case material
<casing>aluminum</casing>
<condition>
ammunition
required, if not factory new
new, remanufactured, surplus, seconds
Condition of ammunition
<condition>new</condition>
<purchaselimit>
ammunition
required if store policy has limit of less than 1000 rounds total
integer (digits only)
Max number of boxes per order
<purchaselimit>5</purchaselimit>
<minpurchase>
ammunition
required if store requires purchase of more than 2 box
integer (digits only)
Minimum purchase required
<minpurchase>2</minpurchase>
<rebate>
ammunition
optional
decimal / only digits and [optionally] a decimal point
Amount (in dollats) the customer could get back (after the sale) via a mail-in rebate or similar mechanism
<rebate>5.00</rebate>
FINAL NOTES (some important items are worth repeating)
The feed should be updated in real-time, or at least every five minutes.
Once we send the request to your server to fetch your data feed, it must respond within 90 seconds, or our system will give up. We typically fetch all data feeds every 3 minutes.
The feed should include only in-stock/available products, or clearly indicate whether the
product is in-stock or not by a field like <qty_available>72</qty_available> or
<availability>in stock</availability>.
When applicable, each product should include a UPC or MPN, either in the <upc> field or in
the product title (<title>) somewhere.
You must list all products of a given type. For example, if you choose
to list ammunition with us,
the feed must include all in-stock ammo your store sells, not only a subset.
The <title> field must be as detailed as possible, but not overly lengthy (160 characters or
less)..
The fields <shot_size>, and <shell_length> need only be populated for shotgun ammo.
For shotgun ammo, the <shot_size> should either be the shot size (e.g. #2, OO, etc) or "slug" if it's a slug. If it contains multiple shot sizes, you can list them all like "4&5" or "7,8,9".
For fields that have special characters such as "&", the whole field should be escaped using a
CDATA section as in the example below. e.g. 40 S&W would be:
<![CDATA[40 S&W]]>
It would be acceptable for all data fields to be escaped in this way. Alternatively, special characters such as <, >, and & can be specified using the appropriate character entites (<, >, and &). These character references should never be used inside a CDATA section.
The caliber in the <caliber> field should be as specific as possible so it can match one of
the calibers listed here: Caliber List (please choose just one caliber name). For
example, a caliber such as "22" will not suffice as it is ambiguous; it could be .22 Long, .22LR,
.22 BB, .22 CB, .22 Short, .22 Win Auto, .22 WMR, or .22 Win Rimfire.
"Combo packs" of varying calibers, types, or quantities should be excluded from the feed.
If you offer several quantity variations for the same
product (say, 100/250/500/1000/2500/5000 round options),
we require that you limit the variations that you include in your
feed to three (perhaps the highest, the lowest, and one in the middle) so that it does not appear
that you're spamming our search results. Each variation will be a separate XML record, and will
have appropriate <price> and <numrounds> fields populated. For items other than ammo,
this limit isn't strictly enforced, within reason.
If you offer bulk discounts: For best results, this should appear in the data feed as multiple
records.
Examples:
You offer a per-box discount for, say, 20+ boxes ordered. You'll have one record
with a normal product title and the price for one box. Then, you'll have another record with
a product title that includes "(Price per box for orders of 20+ boxes)" and the price is the
discounted per-box price. The <numrounds> field should stil be a the number of rounds
per box.
You offer a discount for a case of, say, 20 boxes. You'll have one record with a
normal product title and the price for one box. Then, you'll have another record with a
product title that includes "(Price for case of 20 boxes)" and the price for the entire case.
The <numrounds> field should be a total number of rounds in the case.
All products included in the feed must be "unconditionally available". i.e. purchasable on their own, without additional purchase requirements. (For example, a 1-box limit combined with a $99 minimum order does not meet this requirement). Similarly, all products included in the feed must be purchasable by the general public. Please exclude items available only to "law enforcement", paid subscribers, or club members. Also all items must be orderable directly from your online store, and deliverable to customer's home or FFL (i.e. no "in-store only" items).
Free shipping: If you have specific items that will ship for free, please add the words "FREE SHIPPING" to the
product title, and our system will denote this in the shipping column in our search results.
Conditionally Free shipping: If you have specific items that will ship for free when a condition is met (e.g.
free shipping on orders of 5+ boxes) please indicate this in the product title, and we'll denote this
appropriately with an icon in the shipping column in our listings.
Muzzleloading / Black powder items are not supported at this time, and should be excluded from the data feed.
Extra fees (above and beyond sales tax and shipping costs) must be disclosed in the data feed. This can be done simply by adding text such as "$20 HAZMAT fee required" (or whatever the case may be) to the relevant product titles. Ammoseek can assist with this if the fees apply to all products of a given product type, like primers and powder. Let us know.
Rebates - You can use the <rebate> field to indicate the amount the customer could get
back (after the sale) via a mail-in rebate or similar mechanism.
Suggestions for Feed Help
E-Commerce/Shopping Cart Support (and other external feed help):
3rd Party Developer - the following developers have experience with our feed requirements and should be able to help you out:
CTX Feed - plugin for WooCommerce. WARNING: This may default to a 60 minute feed generation interval. If so, you must contact the developer and request a change to allow for a 5-minute update interval.
Store Pro - eCommerce development and maintenance services, mostly on the WooCommerce and Magento platforms
Gearfire - full service eCommerce solution with excellent AmmoSeek integration
AmmoReady - [only if you manage your own inventory, and do not drop-ship directly from distributors] a complete Gun Ecommerce/Point-of-Sale/Dropshipping solution, including an add-on that generates an AmmoSeek-ready data feed
DataFeedWatch - DO NOT USE - DataFeedWatch cannot be used, because even if you purchase their most expensive plan, the best they'll do is update your feed every 60 minutes, which is nowhere close to what we need)
FeedGeni - DO NOT USE - FeedGeni cannot be used; maximum refresh time is 1-2 hours.
Please note these are 3rd-party plugins and services and that we are not
able to provide assistance or advice with respect to configuration on your end.
A
D
I
N
G