Developer Resources

Offer Import using XML

This document explains how to create a feed that contains information about your discount offers and the vendors and locations where those coupons are valid.

Sample Feeds

Example 1: Basic Complete Feed

<?xml version="1.0" encoding="UTF-8"?>
<listings>
<provider>
    <provider_id>1</provider_id>
    <name>Abenity</name>
    <logo_url>http://www.abenity.com/images/logo_url.jpg</logo_url>
    <url>http://www.abenity.com</url>
</provider>
<client_id>78<client_id>
<vendor>
    <provider_vendor_id>8</provider_vendor_id>
    <name>Acme Widgets</name>
    <description>Acme has produced custom widgets since 1895.</description>
    <address>1234 Main st. suite 200</address>
    <city>Springfield</city>
    <state>IL</state>
    <zip>62701</zip>
    <country>US</country>
    <phone>(234)-234-2300</phone>
    <fax>(234)-234-2301</fax>
    <url>http://www.acme.com</url>
    <logo_url>http://www.mysite.com/logos/acme.jpg</logo_url>
    <owner>
        <name>Jane Smith</name>
        <title>Franchise Owner</title>
        <phone>(234)-234-2345</phone>
        <email>jane@store.com</email>
    </owner>
    <contact_person>
        <name>John Willson</name>
        <title>Sales Manager</title>
        <phone>(234)-234-2346</phone>
        <email>john@store.com</email>
    </contact_person>
    <locations>
        <location>
            <provider_location_id>1001</provider_location_id>
            <name>Acme main branch</name>
            <address>1234 Main st.</address>
            <city>Springfield</city>
            <state>IL</state>
            <zip>62701</zip>
            <country>US</country>
            <latitude>39.80004</latitude>
            <longitude>-89.64953</longitude>
            <phone>(234)-234-2300</phone>
            <fax>(234)-234-2301</fax>
        </location>
    </locations>
    <offers>
        <offer>
            <provider_offer_id>101</provider_offer_id>
            <category_id>23</category_id>
            <title>10% off any custom widget</title>
            <full_description>Acme produces customized widgets for any of your home or office needs. We are ready to fill your order any time. Please come in and see us!</full_description>
            <disclaimer>Acme does not provide service to any Looney Tunes.</disclaimer>
            <offer_url>http://www.acme.com/products/widgets/offeroftheweek.html</offer_url>
            <rebate_url>http://www.acme.com/products/widgets/offerflyer.pdf</rebate_url>
            <promo_url>http://www.acme.com/products/widgets/promoflyer.pdf</promo_url>
            <coupon_code>ACME2009</coupon_code>
            <printable_coupon>1</printable_coupon>
            <mobile_coupon>1</mobile_coupon>
            <phone_instruction>Call (234)-234-2300 and ask for John. Mention the coupon code ACME 2009</phone_instruction>
            <store_instruction>Show your Abenity card or printed coupon at the register.</store_instruction>
            <start_date>2009-01-01</start_date>
            <exp_date>2009-12-13</exp_date>
            <display_range>national</display_range>
            <region>midwest</region>
        </offer>
    </offers>
    <offer_location>
        <provider_offer_id>101</provider_offer_id>
        <provider_location_id>1001</provider_location_id>
    </offer_location>
</vendor>
</listings>
    

Example 2: Simplest Complete Feed

<?xml version="1.0" encoding="UTF-8"?>
<listings>
<provider>
    <provider_id>1</provider_id>
    <name>Abenity</name>
    <url>http://www.abenity.com</url>
</provider>
<vendor>
    <provider_vendor_id>8</provider_vendor_id>
    <name>Acme Widgets</name>
    <url>http://www.acme.com</url>
    <logo_url>http://www.mysite.com/logos/acme.jpg</logo_url>
    <contact_person>
        <name>John Willson</name>
        <title>Sales Manager</title>
        <phone>(234)-234-2346</phone>
        <email>john@store.com</email>
    </contact_person>
    <offers>
        <offer>
            <provider_offer_id>101</provider_offer_id>
            <category_id>23</category_id>
            <title>10% off any custom widget</title>
            <full_description>Acme produces customized widgets for any of your home or office needs. We are ready to fill your order any time. Please come in and see us!</full_description>
            <offer_url>http://www.acme.com/products/widgets/offeroftheweek.html</offer_url>
            <start_date>2009-01-01</start_date>
            <exp_date>2009-12-13</exp_date>
        </offer>
    </offers>
</vendor>
</listings>
    

Feed Format

Your XML file(s) must follow these guidelines:

  • All data values, including URLs, in your feed must use escape codes for the characters listed in the following table. You can use either the entity code or the character code to represent these special characters.

    Character Entity Character Code
    Ampersand & &amp; &#38;
    Single Quote ' &apos; &#39;
    Double Quote " &quot; &#34;
    Greater Than > &gt; &#62;
    Less Than < &lt; &#60;
    Copyright © unsupported &#169;
    Registered trademark ® unsupported &#174;
    Trademark unsupported &#8482;
  • Your feed must use UTF-8 encoding. Please specify this encoding schema by including the encoding attribute in your XML tag as shown in the sample XML below.

  • XML tags without data should be omitted from your feed.

  • XML tags should not contain HTML unless the XML tag definition explicitly specifies that HTML markup is acceptable.

XML Tag Definitions

This section lists the XML tags and subtags that you will need to include in your feed. The tags are listed alphabetically. Each listing includes:

  • The name of the tag
  • A definition of the tag
  • Any attributes that may be provided for the tag
  • An example of the tag as it is used in the sample XML
  • A list of the subtags associated with the tag
  • A list of the tags that the tag is a subtag of
  • The content format of the tag

Note: Please omit optional tags from your feed if you do not have values for those tags. For example, if you do not have the latitudes and longitudes for the businesses in your feed, please omit the <latitude> and <longitude> tags from your feed.

Subtags Legend

Certain symbols may be displayed next to some subtags in the definitions below. These symbols, and their meanings, are:

? = optional subtag
* = zero or more instances of the subtag
+ = one or more instances of the subtag

address
Definition The <address> specifies the street address of the parent tag.
Example <address>1234 Main st. suite 200</address>
Subtags None
Subtag of vendor, location
Content Format Text. 50 Characters Max.
Required Required if parent tag exists.
category_id
Definition The <category_id> is a unique identifier that assigns the offer to a particular industry of product or service. A lookup table of category_ids is available here: Abenity Category Table
Example <category_id>23</category_id>
Subtags None
Subtag of offer
Content Format Unsigned Int, (1-65535)
Required Yes
client_id
Definition The <client_id> is a unique identifier that assigns the offer to a particular client. This number will be provided by Abenity upon request.
Example <client_id>78</client_id>
Subtags None
Subtag of listing
Content Format Unsigned Int, (1-65535)
Required Yes
city
Definition The <city> specifies the city of the parent tag.
Example <city>Springfield</city>
Subtags None
Subtag of vendor, location
Content Format Text. 50 Characters Max.
Required Required if parent tag exists.
contact_person
Definition The <contact_person> tag encapsulates information about the primary point-of-contact with the business (vendor).
Example <vendor>
Subtags name, title, phone email
Subtag of vendor
Content Format Empty
Required No
country
Definition The <country> specifies the country of the parent tag.
Example <country>US</country>
Subtags None
Subtag of vendor, location
Content Format Text (a two-letter ISO state code)
Required Required if parent tag exists.
coupon_code
Definition The <coupon_code> is a code that must be mentioned at checkout in order to redeem the offer.
Example <coupon_code>ACME2009</coupon_code>
Subtags None
Subtag of offer
Content Format Text. 32 Characters Max.
Required No. However one of the following actionable options must be included: offer_url, rebate_url, coupon_code, printable_coupon, phone_instruction or store_instruction
description
Definition The <name> specifies the name of the vendor entity supplying the offer(s).
Example <vendor>Acme Widgets</vendor>
Subtags None
Subtag of vendor
Content Format Text
Required Yes
disclaimer
Definition The <disclaimer> should describe any limitations to the offer.
Example <disclaimer>Acme does not provide service to any Looney Tunes.</disclaimer>
Subtags None
Subtag of offer
Content Format Text. No HTML.
Required No
display_range
Definition The <display_range> indicates how broadly to publish the offer. This tag is required, however the default value will be set to Local.
Example <display_range>Local</display_range>
Subtags None
Subtag of offer
Content Format Text. Valid values are: international, continental, national, regional, state, Local.
Required Yes
email
Definition The <email> specifies the email address of the parent tag.
Example <email>(234)-234-2300 x123</email>
Subtags None
Subtag of contact_person
Content Format Text. 100 Characters Max. Must be in the form name@domain.com and pass the regular expression: ['0-9a-zA-Z~!#$%&_-]([.]?[0-9a-zA-Z~!#$%&_-])*@[0-9a-zA-Z~!#$%&_-]([.]?[0-9a-zA-Z~!#$%&_-])*$
Required No
email
Definition The <email> specifies the email address of the owner.
Example <email>(234)-234-2300 x123</email>
Subtags None
Subtag of owner
Content Format Text. 100 Characters Max. Must be in the form name@domain.com and pass the regular expression: ['0-9a-zA-Z~!#$%&_-]([.]?[0-9a-zA-Z~!#$%&_-])*@[0-9a-zA-Z~!#$%&_-]([.]?[0-9a-zA-Z~!#$%&_-])*$
Required Yes
exp_date
Definition The <exp_date> indicates the date at which the offer expires. If this is not provided the expiration date will become the date the feed is processed plus one year.
Example <exp_date>2010-01-01</exp_date>
Subtags None
Subtag of offer
Content Format Date. YYYY-MM-DD.
Required No
fax
Definition The <fax> specifies the fax number for the parent element.
Example <fax>(234)-234-2301</fax>
Subtags None
Subtag of vendor, location
Content Format Text. 25 Characters Max. Must pass Regular Expression: ^(\()?([2-9]{1}[0-9]{2})([) -.]{0,2})([0-9]{3})([- .]?)([0-9]{4}[ ]?)(ext|Ext|x|X)?(\s|\.|\. )?(\d*)?$^. The number will be auto-formatted if it passes this expression.
Required Required if parent tag exists.
full_description
Definition The <full_description> should fully describe the offer in as much detail as possible while still leaving it succinct enough to keep it interesting - &qout;Long enough to cover the subject, but short enough to keep it interesting", as they say. Make use of the <disclaimer> tag to note any exceptions.
Example <full_description>Acme produces customized widgets for any of your home or office needs. We are ready to fill your order any time. Please come in and see us!</full_description>
Subtags None
Subtag of offer
Content Format Text. HTML markup is allowed, however it is subject to review.
Required Yes
latitude
Definition The <latitude> specifies the geographic latitude of the location.
Example <latitude>39.80004</latitude>
Subtags None
Subtag of location
Content Format Floating-point number between "-180.0" and "180.0" inclusive
Required No
listings
Definition The <listings> tag encapsulates all of the store listings and coupons in the feed.
Example <listings>
Subtags provider, vendor+
Content Format Empty
Required Yes
Required Yes
location
Definition The <location> tag encapsulates information about a business (vendor) location.
Example <location>
Subtags provider_location_id, name, address, city, state, zip, country, latitude, longitude, phone, fax
Subtag of locations
Content Format Empty
Required No
locations
Definition The <locations> tag includes information about many locations.
Example <locations>
Subtags locations
Subtag of vendor
Content Format Empty
Required No
logo_url
Definition The <logo_url> specifies a WWW hyperklink to the vendor&38217;s logo. Logos should be no wider than 200px and no taller than 56px. Larger images will be resized to meet these specifications.
Example <logo_url>http://www.mysite.com/logos/acme.jpg</logo_url>
Subtags None
Subtag of vendor, provider
Content Format Text. 200 Characters Max. Must begin with http:// or https://. If it does not, then http:// will be appended as a prefix. The link must point to an image of the file type: JPG, GIF or PNG.
Required Yes
longitude
Definition The <longitude> specifies the geographic longitude of the location.
Example <longitude>89.64953</longitude>
Subtags None
Subtag of location
Content Format Floating-point number between "-180.0" and "180.0" inclusive
Required No
name
Definition The <name> specifies the name of the vendor entity supplying the offer(s).
Example <provider>Acme Widgets</provider>
Subtags None
Subtag of vendor
Content Format Text. This value may be up to 100 characters long and may only contain the following characters: a-z, A-Z, 0-9, ".", "-", "'"
Required Yes
name
Definition The owner <name> tag encapsulates the name of the business (vendor) owner.
Example <name>Jane Smith<name>
Subtags None
Subtag of owner
Content Format Text. 50 Characters Max.
Required Yes
name
Definition The <name> specifies the name of the provider entity supplying the feed.
Example <provider>Abenity</provider>
Subtags None
Subtag of provider
Content Format Text. This value may be up to 120 characters long and may only contain the following characters: a-z, A-Z, 0-9, ".", "-"
Required Yes
offer
Definition The <offer> tag encapsulates information about a discount offer.
Example <offer>
Subtags provider_offer_id, category_id, title, full_description, disclaimer, offer_url, rebate_url, promo_url, coupon_code, printable_coupon, mobile_coupon, phone_instruction, store_instruction, store_instruction, start_date, exp_date, display_range, region,
Subtag of offers
Content Format Empty
Required Yes
offers
Definition The <offers> tag includes information about many offers.
Example <offers>
Subtags offer
Subtag of vendor
Content Format Empty
Required Yes
offer_location
Definition The <offer_location> tag pairs offers and locations. Because Vendors may have multiple offers and multiple locations, and because all locations may not support all offers, it is important to group the offers and their supportive locations. For each offer, include an <offer_location> tag that begins with <provider_offer_id> as the first subtag, followed by 1 or more <provider_location_id> subtags that are supported by the above provider_offer_id. Using this structure the same provider_location_id may be associated with many provider_offer_ids and each provider_offer_id should only be listed once.
Example <offer_location>
Subtags provider_location_id, provider_offer_id
Subtag of vendor
Content Format Empty
Required Required if there is more than one vendor and more than one offer.
offer_url
Definition The <offer_url> is a WWW hyperlink to a web site continue more information on the offer or capable of processing the discount.
Example <offer_url>http://www.acme.com/products/widgets/offeroftheweek.htm</offer_url>
Subtags None
Subtag of offer
Content Format Text. 200 Characters Max. Must begin with http:// or https://. If it does not, then http:// will be appended as a prefix.
Required No. However one of the following actionable options must be included: offer_url, rebate_url, coupon_code, printable_coupon, phone_instruction or store_instruction
owner
Definition The <owner> tag encapsulates information about a business (vendor) owner.
Example <owner>
Subtags name, title, phone, email
Subtag of vendor
Content Format Empty
Required No
phone
Definition The <phone> specifies the phone of the parent element.
Example <phone>(234)-234-2300 x123</phone>
Subtags None
Subtag of vendor, owner, contact_person, location
Content Format Text. 25 Characters Max. Must pass Regular Expression: ^(\()?([2-9]{1}[0-9]{2})([) -.]{0,2})([0-9]{3})([- .]?)([0-9]{4}[ ]?)(ext|Ext|x|X)?(\s|\.|\. )?(\d*)?$^. The number will be auto-formatted if it passes this expression.
Required Required if parent tag exists.
phone
Definition The <phone> specifies the phone number of the owner.
Example <phone>(234)-234-2300 x123</phone>
Subtags None
Subtag of owner
Content Format Text. 25 Characters Max. Must pass Regular Expression: ^(\()?([2-9]{1}[0-9]{2})([) -.]{0,2})([0-9]{3})([- .]?)([0-9]{4}[ ]?)(ext|Ext|x|X)?(\s|\.|\. )?(\d*)?$^. The number will be auto-formatted if it passes this expression.
Required No
phone
Definition The <phone> specifies the phone number of the contact person.
Example <phone>(234)-234-2300 x123</phone>
Subtags None
Subtag of contact_person
Content Format Text. 25 Characters Max. Must pass Regular Expression: ^(\()?([2-9]{1}[0-9]{2})([) -.]{0,2})([0-9]{3})([- .]?)([0-9]{4}[ ]?)(ext|Ext|x|X)?(\s|\.|\. )?(\d*)?$^. The number will be auto-formatted if it passes this expression.
Required No
phone_instruction
Definition The <phone_instruction> provides optional information about how to redeem the offer over the phone. Try and match the format &qout;Call (phone number) and (perform this action)"
Example <phone_instruction>Call (234)-234-2300 and ask for John. Mention the coupon code ACME 2009</phone_instruction>
Subtags None
Subtag of offer
Content Format Text.
Required No. However one of the following actionable options must be included: offer_url, rebate_url, coupon_code, printable_coupon, phone_instruction or store_instruction
printable_coupon
Definition The <printable_coupon> defines whether or not the offer listing should include a link to a standardized, printer-friendly coupon format.
Example <coupon_code>1</coupon_code>
Subtags None
Subtag of offer
Content Format Binary. 1 = provide printable coupon. 0 = do not provide printable coupon
Required No. However one of the following actionable options must be included: offer_url, rebate_url, coupon_code, printable_coupon, phone_instruction or store_instruction
mobile_coupon
Definition The <mobile_coupon> defines whether or not the vendor making the offer will accept a mobile phone display as a valid coupon.
Example <mobile_coupon>1</mobile_coupon>
Subtags None
Subtag of offer
Content Format Binary. 1 = supports mobile coupon. 0 = does not support mobile coupon
Required No. However one of the following actionable options must be included: offer_url, rebate_url, coupon_code, printable_coupon, phone_instruction or store_instruction
promo_url
Definition The <promo_url> is a WWW hyperlink to a document that contains promotional information about the discount, such as a PDF flyer.
Example <promo_url>http://www.acme.com/products/widgets/promoflyer.pdf</promo_url>
Subtags None
Subtag of offer
Content Format Text. 200 Characters Max. Must begin with http:// or https://. If it does not, then http:// will be appended as a prefix.
Required No
provider
Definition The <provider> tag encapsulates information about the provider of the feed.
Example <provider>
Subtags url, name
Subtag of listings
Content Format Empty
Required Yes
provider_id
Definition The <provider_id> is a unique identifier assigned to the provider of the XML feed.
Example <provider>1</provider>
Subtags None
Subtag of provider
Content Format Unsigned Int, (1-255)
Required Yes
provider_location_id
Definition The <provider_location_id> is a unique identifier assigned to the location by the provider of the XML feed. This value must remain the same across feeds in order for the offer to be updated and not re-created.
Example <provider_location_id>1001</provider_location_id>
Subtags None
Subtag of location
Content Format Unsigned Int, (1-16777215)
Required Yes
provider_offer_id
Definition The <provider_offer_id> is a unique identifier assigned to the offer by the provider of the XML feed. This value must remain the same across feeds in order for the offer to be updated and not re-created. Additionally, this value will appear in direct URLs to the offer so it is desirable for it to be as short as possible.
Example <provider_offer_id>101</provider_offer_id>
Subtags None
Subtag of offer
Content Format Unsigned Int, (1-4294967295)
Required Yes
provider_vendor_id
Definition The <provider_vendor_id> is a unique identifier assigned to the vendor by the provider of the XML feed. This value must remain the same across feeds in order for the vendor to be updated and not re-created.
Example <provider_vendor_id>12</provider_vendor_id>
Subtags None
Subtag of vendor
Content Format Unsigned Int, (1-16777215)
Required Yes
rebate_url
Definition The <rebate_url> is a WWW hyperlink to a web page that contains instructions for redeeming a rebate.
Example <rebate_url>http://www.acme.com/products/widgets/offerflyer.pdf</rebate_url>
Subtags None
Subtag of offer
Content Format Text. 200 Characters Max. Must begin with http:// or https://. If it does not, then http:// will be appended as a prefix.
Required No. However one of the following actionable options must be included: offer_url, rebate_url, coupon_code, printable_coupon, phone_instruction or store_instruction
region
Definition The <region> indicates a broader range of relevance for the offer. This field should be omitted unless there is a specific agreement between the Provider and Abenity on how this will be used.
Example <region>midwest</region>
Subtags None
Subtag of offer
Content Format Text.
Required No
start_date
Definition The <start_date> indicates the date at which the offer becomes effective. If this is not provided the start date will become the date the feed is processed.
Example <start_date>2009-01-01</start_date>
Subtags None
Subtag of offer
Content Format Date. YYYY-MM-DD.
Required No
state
Definition The <state> specifies the state / province of the parent tag.
Example <state>IL</state>
Subtags None
Subtag of vendor, location
Content Format Text (a two-letter ISO state code)
Required Required if parent tag exists.
store_instruction
Definition The <store_instruction> provides optional information about how to redeem the offer in person at a store. Include information such as, &qout;present coupon", "ask for the Abenity discount", etc.
Example <phone_instruction>Show your Abenity card or printed coupon at the register.</phone_instruction>
Subtags None
Subtag of offer
Content Format Text.
Required No. However one of the following actionable options must be included: offer_url, rebate_url, coupon_code, printable_coupon, phone_instruction or store_instruction
title
Definition The <title> is the offer in a nutshell. It should describe the discount in as few words as possible while communicating its value.
Example <title>10% off any custom widget</title>
Subtags None
Subtag of offer
Content Format Text. 255 Characters Max. No HTML.
Required Yes
title
Definition The contact_person <title> tag encapsulates the business title of the business (vendor) contact person, e.g. (Manager, Staff, etc.)
Example <title>Franchise Owner<title>
Subtags None
Subtag of contact_person
Content Format Text. 50 Characters Max.
Required No
title
Definition The owner <title> tag encapsulates the business title of the business (vendor) owner, e.g. (Owner, President, Manager, etc.)
Example <title>Franchise Owner<title>
Subtags None
Subtag of owner
Content Format Text. 50 Characters Max.
Required Yes
url
Definition The <url> specifies a WWW hyperlink to the provider supplying the feed.
Example <provider>http://www.abenity.com</provider>
Subtags None
Subtag of provider
Content Format Text
Required Yes
url
Definition The <url> specifies a WWW hyperklink to the vendor&38217;s web site.
Example <url>http://www.acme.com</url>
Subtags None
Subtag of vendor
Content Format Text. 100 Characters Max. Must begin with http:// or https://. If it does not, then http:// will be appended as a prefix.
Required Yes
vendor
Definition The <vendor> tag encapsulates information about a business (vendor) that provides a discount.
Example <vendor>
Subtags provider_vendor_id, name, description, address, city, state, country, phone, fax, url, logo_url, owner, contact_person, locations*, offers+
Subtag of listings
Content Format Empty
Required Yes
zip
Definition The <zip> specifies the ZIP code of the parent tag.
Example <zip>62701</zip>
Subtags None
Subtag of vendor, location
Content Format Text. A valid alphanumeric postal ZIP code. 10 Characters Max.
Required Required if parent tag exists.

Appendix

Appendix A - About XML Schemas

XML schemas provide an XML-based method of describing the structure of an XML document. XML schemas use the *.xsd file extension. Like DTD files, XML schemas define the elements and attributes that can appear in a document, indicate whether elements are empty or contain text, and define parent-child relationships between different XML elements.

XML schemas are different from DTDs in a number of ways. For the purpose of creating a feed for Abenity, it is important to understand a couple of these differences. First, XML schemas support data types, meaning they can define whether a particular field should hold an integer, string, date, float or other type of value. Second, XML schemas can restrict the acceptable set of values for a given field. In addition to defining a field as a string, an XML schema can also provide a list of acceptable strings for that field. Similarly, XML schemas can define an acceptable range of integers for an integer field.

You can learn more about XML schemas from this XML schema tutorial or the W3C's XML Schema Primer.

XML Schema Validation Tools

There are a number of tools available to help you validate the structure of your XML feed(s). You can find a list of XML-related tools at each of the following locations:

Abenity A

Request a Live Demo

I’m Missy Dunn, our Director of Sales here at Abenity. I’d love to know more about your organization and discuss how we can help with your member, alumni, or employee perks. Let’s talk!

Missy Dunn, Director of Sales
Powered by:
GoToMeeting Logo

Take a Self-Guided Tour of Abenity

With these short videos led by Brian Roland, Abenity’s Co-Founder and CEO, you’ll learn more about how we do things here at Abenity and why we care so much about perks. After viewing, you’ll have free access to tour our program, download our mobile apps, and check out our perks.

INTRO (1:07)

SIMPLE (1:08)

TRANSPARENT (1:58)

SAVINGS (2:22)


Start Your Tour

Select Topics of Interest:

Log In

Watch Our Story Video

Loading video…