Offer Feed XML Specification V2

This document defines the XML feed format that vendors must use to provide their product offers. It is designed to ensure that all feeds are consistent, valid, and easily integrated into our system.

Note: This specification is for version 2 of the offer feed. Be sure your implementation adheres to these rules to avoid feed rejections.

View Schema Validate XML

Overview

The XML document should have a root element named offers that contains a list of offers elements. Each offers element represents a single offer and must include essential details such as the price, status, and a link to the vendor's store, along with other pertinent information. While the specific contents of an offers element may vary depending on the type of offer (for example, ammunition, weapons, parts, reloading supplies, etc.), every offer must include all required fields to be considered valid for listing.

Important Notes:

The contents of an offer may vary depending on the offer type (e.g., ammunition, weapons, parts, reloading, etc.).
Every offer must include all required data to be eligible for listing.
Certain elements are mutually exclusive and will vary based on the specific offer type.

<?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 Type Tabs


                        <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.

<offer>
    <upc>123456789012</upc>
    <mpn>35521</mpn>
    <name>Hornady 9mm 115gr XTP Bullets - 100ct</name>
    <brand>Hornady</brand>
    <url>https://example.com/hornady-9mm-bullets</url>
    <availability>in stock</availability>
    <price>24.99</price>
    <shippingInfo>Free shipping over $150</shippingInfo>
    <imageUrl>https://example.com/images/35521.jpg</imageUrl>
    <reloading>
        <type>bullet</type>
        <numberOfRounds>100</numberOfRounds>
        <bulletCaliber>9mm</bulletCaliber>
    </reloading>
    </offer>

<offer>
    <upc>123456789013</upc>
    <mpn>R9MM100</mpn>
    <name>Starline 9mm Luger Brass Cases - 100ct</name>
    <brand>Starline</brand>
    <url>https://example.com/starline-9mm-brass</url>
    <availability>in stock</availability>
    <price>32.99</price>
    <shippingInfo>Free shipping over $150</shippingInfo>
    <imageUrl>https://example.com/images/R9MM100.jpg</imageUrl>
    <reloading>
        <type>brass</type>
        <numberOfRounds>100</numberOfRounds>
        <brassCartridge>9mm Luger</brassCartridge>
    </reloading>
    </offer>

<offer>
    <upc>123456789014</upc>
    <mpn>SP100</mpn>
    <name>CCI Small Pistol Primers #500 - 1000ct</name>
    <brand>CCI</brand>
    <url>https://example.com/cci-small-pistol-primers</url>
    <availability>in stock</availability>
    <price>89.99</price>
    <shippingInfo>Hazmat fee applies</shippingInfo>
    <imageUrl>https://example.com/images/SP100.jpg</imageUrl>
    <reloading>
        <type>primer</type>
        <numberOfRounds>1000</numberOfRounds>
        <primerSize>small pistol</primerSize>
    </reloading>
    </offer>

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>`

FAQs

What is the primary purpose of the Offer Feed XML Specification V2?

It standardizes the format for weapon and ammunition listings, ensuring consistency and compatibility with platforms.

How often should the XML feed be updated?

Regular updates are recommended to reflect real-time product availability, pricing, and specifications, enhancing user trust.

Are there image guidelines within this specification?

Yes, images should be high-resolution, in formats like JPEG or PNG, and free from watermarks or promotional text.

Can I include custom attributes in my XML feed?

Absolutely. Custom attributes like brand, caliber, and condition can be added to provide detailed product information.

How does this specification differ from Google's Product Data Specification?

While both are XML-based, the Offer Feed XML Specification V2 is tailored for weapon and ammunition listings, whereas Google's specification caters to a broader range of e-commerce products.

Is adherence to this specification mandatory for listing?

While not mandatory, adhering to the specification ensures seamless integration and optimal presentation of your products on the platform.