Offer Feed XML V2 Specification

The following document provides detailed instructions about XML file format that we use as a source for our weapons, ammunition and other guns-related listings. Feed format explained here is used to import these offers.

Feed should be a valid XML document defined by this schema. You can manually validate your XML file using this validator.

Overview

The XML should contain offers as a root element with the list of offer elements as its children. Every offer element describes one offer, with its price, status, a link to the vendor's store, and other useful information. The contents of an offer element may differ based on the offer type (ammunition, weapon, parts, reloading, etc.). An offer must include all required data in order to be listed.

This is a brief overview of the XML file format. Note that some elements are mutually exclusive and required based on the offer type. Read the full specification for details.

<?xml version="1.0" encoding="UTF-8" ?>
<offers xmlns="https://api.gunengine.com/ingest/XMLSchema/feed/v2/offers">
    <!-- Ammo -->
    <offer>
        <upc>...</upc>
        <mpn>...</mpn>
        <name>...</name>
        <brand>...</brand>
        <url>...</url>
        <availability>...</availability>
        <price>...</price>
        <shippingInfo>...</shippingInfo>
        <imageUrl>...</imageUrl>
        <ammunition>required for ammo</ammunition>
    </offer>

    <!-- Firearm -->
    <offer>
        <upc>...</upc>
        <mpn>...</mpn>
        <name>...</name>
        <brand>...</brand>
        <url>...</url>
        <availability>...</availability>
        <price>...</price>
        <shippingInfo>...</shippingInfo>
        <imageUrl>...</imageUrl>
        <firearm>required for firearm</firearm>
    </offer>

    <!-- Part -->
    <offer>
        <upc>...</upc>
        <mpn>...</mpn>
        <name>...</name>
        <brand>...</brand>
        <url>...</url>
        <availability>...</availability>
        <price>...</price>
        <shippingInfo>...</shippingInfo>
        <imageUrl>...</imageUrl>
        <part>required for part</part>
    </offer>

    <!-- Reloading -->
    <offer>
        <upc>...</upc>
        <mpn>...</mpn>
        <name>...</name>
        <brand>...</brand>
        <url>...</url>
        <availability>...</availability>
        <price>...</price>
        <shippingInfo>...</shippingInfo>
        <imageUrl>...</imageUrl>
        <reloading>required for reloading</reloading>
    </offer>

    <!-- Other products -->
    <offer>
        <upc>...</upc>
        <mpn>...</mpn>
        <name>...</name>
        <brand>...</brand>
        <url>...</url>
        <availability>...</availability>
        <price>...</price>
        <shippingInfo>...</shippingInfo>
        <imageUrl>...</imageUrl>
    </offer>
</offers>

<?xml version="1.0" encoding="UTF-8" ?>
<offers xmlns="https://api.gunengine.com/ingest/XMLSchema/feed/v2/offers">
    <!-- List of multiple offers -->
    <offer>
        <upc>string</upc> <!-- Required -->
        <mpn>string</mpn> <!-- Recommended -->
        <name>string</name> <!-- Required -->
        <brand>string</brand> <!-- Recommended -->
        <url>https://example.com/url</url> <!-- Required -->
        <availability>string</availability> <!-- Required: "in stock", "out of stock" or "backorder" -->
        <price>1000.00</price> <!-- Required: price in dollars, use attribute hide="MAP" to hide MAP price -->
        <shippingInfo>string</shippingInfo> <!-- Optional: price or 60 chars long textual description -->
        <imageUrl>https://example.com/image.jpg</imageUrl> <!-- Recommended -->
        <!--
            Specification based on the offer type.
            (If your offer is one of the following: ammunition, firearm, part or reloading –
            use the corresponding element. Otherwise, no specification element is needed.)
        -->
            <ammunition>
                <caliber>string</caliber> <!-- Required -->
                <numberOfRounds>1000</numberOfRounds> <!-- Required -->
            </ammunition>
        <!-- or -->
            <firearm>
                <model>string</model> <!-- Recommended: general model name (e.g., Ruger EC9, Glock 43, Sig P290) -->
                <type>string</type> <!-- Optional: type of firearm (e.g., handgun, revolver, rifle) -->
                <action>string</action> <!-- Optional: firearm action (e.g., single, double, semi-auto) -->
                <caliber>string</caliber> <!-- Optional -->
            </firearm>
        <!-- or -->
            <part>
                <type>string</type> <!-- Required: precise part category (e.g., 1911 mag, ar15 lower, ar10 kit) -->
            </part>
        <!-- or -->
            <reloading>
                <type>string</type> <!-- Required: "brass", "bullet" or "primer" -->
                <numberOfRounds>1000</numberOfRounds> <!-- Required -->
                <!-- One of the following is required -->
                    <bulletCaliber>string</bulletCaliber>
                <!-- or -->
                    <brassCartridge>string</brassCartridge>
                <!-- or -->
                    <primerSize>string</primerSize>
            </reloading>
    </offer>
</offers>

Specification

<offers>
    <offer>...</offer>
    <offer>...</offer>
    <offer>...</offer>
</offers>

`offer`

<offer>
    <upc>...</upc>
    <mpn>...</mpn>
    <name>...</name>
    <brand>...</brand>
    <url>...</url>
    <availability>...</availability>
    <price>...</price>
    <shippingInfo>...</shippingInfo>
    <imageUrl>...</imageUrl>
    <ammunition>...</ammunition>
</offer>

<offer>
    <upc>...</upc>
    <mpn>...</mpn>
    <name>...</name>
    <brand>...</brand>
    <url>...</url>
    <availability>...</availability>
    <price>...</price>
    <shippingInfo>...</shippingInfo>
    <imageUrl>...</imageUrl>
    <firearm>...</firearm>
</offer>

<offer>
    <upc>...</upc>
    <mpn>...</mpn>
    <name>...</name>
    <brand>...</brand>
    <url>...</url>
    <availability>...</availability>
    <price>...</price>
    <shippingInfo>...</shippingInfo>
    <imageUrl>...</imageUrl>
    <part>...</part>
</offer>

<offer>
    <upc>...</upc>
    <mpn>...</mpn>
    <name>...</name>
    <brand>...</brand>
    <url>...</url>
    <availability>...</availability>
    <price>...</price>
    <shippingInfo>...</shippingInfo>
    <imageUrl>...</imageUrl>
    <reloading>...</reloading>
</offer>

<offer>
    <upc>...</upc>
    <mpn>...</mpn>
    <name>...</name>
    <brand>...</brand>
    <url>...</url>
    <availability>...</availability>
    <price>...</price>
    <shippingInfo>...</shippingInfo>
    <imageUrl>...</imageUrl>
</offer>

Element	Requirement	Constraints	Description	Examples
`<upc>`	required	digits only	Universal product code (barcode number) in the one of common formats (e.g., UPC-A, EAN, GTIN-12, GTIN-13, GTIN-14). Do not fill this field with internal ids or invalid codes, because the offer will not be listed in that case.	Good `<upc>082442908144</upc>` Bad not UPC `<upc>ABCD123</upc>` Bad not UPC `<upc>12</upc>`
`<mpn>`	recommended		Manufacturer product number is the identification number issued and used by the manufacturer. Use the original MPN, without adding additional characters to identify manufacturer or features. Do not fill this field with internal stock keeping numbers, or other codes, because the offer may not be listed in that case.	Good `<mpn>J92FR915G</mpn>` Bad brand prefix `<mpn>BERETTA-J92FR915G</mpn>`
`<name>`	required		Concise product name. Shouldn't be to long, but it needs to contain enough information to identify the product. Do not include product unrelated information, such as promotions, sale info, emojis, etc.	Good `<name>Beretta 92X GR Full Size 9mm</name>` Bad to vague `<name>Beretta 92</name>` Bad not product related `<name>Beretta 92X GR \| On Sale - 3 Left</name>`
`<brand>`	recommended		Brand (manufacturer) name.	Good `<brand>Beretta</brand>`
`<url>`	required	valid URI	URL pointing to the offer on vendor's website.	Good `<url>https://example.com/beretta-92x-J92FR915G</url>`
`<availability>`	required	"in stock" "out of stock" "backorder"	Current offer availability for online purchasing. Use only one of these values to describe availability: "in stock", "out of stock", "backorder". Do not use different text to describe availability, because the offer may not be listed in that case.	Good `<availability>in stock</availability>` Good `<availability>out of stock</availability>` Bad unsupported value `<availability>OOS</availability>` Bad unsupported value `<availability>Limited (3 Left)</availability>`
`<price>` or `<price hide="MAP">`	required	decimal number	Price value in USD, in decimal notation (without a dollar sign). Add `hide="MAP"`attribute to the element in order to hide the minimum advertised price and show text "MAP" instead. Do not include currency or other text here, because the offer will not be listed in that case. Do not use `hide` attribute for regular price, because the price will not be shown in that case.	Good `<price>1000.00</price>` Good for MAP price `<price hide="MAP">1000.00</price>` Good for MAP price `<price hide="Add to Cart for best price">1000.00</price>` Good for MAP price `<price hide="Any text instead of price">1000.00</price>` Bad dollar sign `<price>$1000.00</price>` Bad currency abbr `<price>1000.00USD</price>`
`<shippingInfo>`	optional	60 chars max	Specify the shipping price, or briefly describe how shipping is calculated.	Good `<shippingInfo>Free shipping over $20</shippingInfo>`
`<imageUrl>`	recommended	valid URI	URL pointing to the offer image.	Good `<imageUrl>https://example.com/J92FR915G.jpg</imageUrl>`
`<ammunition>` or `<firearm>` or `<part>` or `<reloading>`	required (for corresponding offer types)		Additional specification is required for ammunition, firearms, parts and reloading offers. For each offer use the corresponding element. For other offers (e.g., accessories, knives, optics) omit the specification element. See the following chapters for detail description of each specification element. Do not omit specification for ammo, firearm, part or reloading products, because the offer will not be listed in that case.

`ammunition`

This element should be always placed inside offer element for ammunition offers.

<ammunition>
    <caliber>...</caliber>
    <numberOfRounds>...</numberOfRounds>
</ammunition>

Element	Requirement	Constraints	Description	Examples
`<caliber>`	required		Ammunition caliber (cartridge) or shotshell gauge.	Good `<caliber>9mm Luger</caliber>`
`<numberOfRounds>`	required	integer number	Number of ammunition rounds sold in this offer (total rounds sold for the given price).	Good `<numberOfRounds>1000</numberOfRounds>` Bad rounds suffix `<numberOfRounds>1000rnds</numberOfRounds>`

`firearm`

This element should be always placed inside offer element for firearm offers. If it is not possible to fill optional information for this element, just add an empty firearm element to identify the firearm offer.

<firearm>
    <model>...</model>
    <type>...</type>
    <action>...</action>
    <caliber>...</caliber>
</firearm>

Element	Requirement	Description	Examples
`<model>`	recommended	General model name – model name without specific gun properties (e.g., Ruger EC9, Glock 43, Sig P290). It is useful to provide this info if possible. This field is different from the offer name, as the name contains enough details to describe an offer, but this field is used to classify offers into appropriate listings.	Good `<model>Glock 19</model>` Bad to vague `<model>Glock</model>` Bad to detailed `<model>Glock 19 Gen3 9mm Night Sights 15rnds</model>`
`<type>`	optional	Firearm type (e.g., handgun, rifle, revolver).	Good `<type>handgun</type>`
`<action>`	optional	Firearm action (e.g., single action, double action, semi-auto).	Good `<action>double action</action>`
`<caliber>`	optional	Firearm caliber.	Good `<caliber>9mm Luger</caliber>`

`part`

This element should be always placed inside offer element for part offers.

<part>
    <type>...</type>
</part>

Element	Requirement	Constraints	Description	Examples
`<type>`	required		Precise part category (e.g., 1911 mag, ar15 lower, ar10 kit). This field is used to classify the part offer into appropriate listing.	Good `<type>1911 magazine</type>` Bad to vague `<type>Magazine</type>` Bad to detailed `<type>ProMag COLA5 Colt 45 ACP</type>`

`reloading`

This element should be always placed inside offer element for reloading offers.

<reloading>
    <type>bullet</type>
    <numberOfRounds>...</numberOfRounds>
    <bulletCaliber>...</bulletCaliber>
</reloading>

<reloading>
    <type>brass</type>
    <numberOfRounds>...</numberOfRounds>
    <brassCartridge>...</brassCartridge>
</reloading>

<reloading>
    <type>primer</type>
    <numberOfRounds>...</numberOfRounds>
    <primerSize>...</primerSize>
</reloading>

Element	Requirement	Constraints	Description	Examples
`<type>`	required	"brass" "bullet" "primer"	Type of reloading supply or equipment. Use only one of these values to describe the type: "brass", "bullet" or "primer".	Good `<type>brass</type>`
`<numberOfRounds>`	required	integer number	Number of rounds/pieces sold in this offer (total rounds sold for the given price).	Good `<numberOfRounds>1000</numberOfRounds>` Bad rounds suffix `<numberOfRounds>1000rnds</numberOfRounds>`
`<bulletCaliber>`	required for bullet		Bullet caliber (diameter) is required for reloading bullet offers.	Good `<bulletCaliber>9mm</bulletCaliber>` Good `<bulletCaliber>.355</bulletCaliber>`
`<brassCartridge>`	required for brass		Brass cartridge name (caliber) is required for brass.	Good `<brassCartridge>9mm Luger</brassCartridge>`
`<primerSize>`	required for primer		Primer size is required for primers.	Good `<primerSize>small pistol</primerSize>`