Introduction

This document will guide you through the processes and requirements involved in adding your stock to our Product Catalogue system using industry standard data transfer methods.

If you have an existing product feed please send this through to your account manager for review – we can usually work with most existing product feeds.

If you do not have a product feed available for affiliates the following services may be useful: http://www.ultimatefeed.com or http://www.fusepump.com

We will import your formatted data into our product catalogue on a regular scheduled basis, either hourly, daily, monthly or on a Merchant specific schedule that fits with your current data processing practices. Product data can also be added to the catalogue on an ad-hoc basis.

Our product catalogue, containing your products, is distributed through our affiliate network and made available as either a raw data feed in XML/CSV or through our Product Feed API as an XML/JSON response.

You will be able to track sales of your products through our tracking system which will identify items sold and commissions due if you also implement our Basket Tracking.

Terminology

Although this document should be accessible to individuals with no technical knowledge, there are a number of common terms and processes used throughout that are briefly explained below.

  • The Product Catalogue is a centralised database of products stored on high specification servers with product data sourced from multiple merchants.
  • A Feed is a structured set of data designed to either populate the central Product Catalogue by Merchants or delivered from the Product Catalogue typically to Affiliates.
  • A Data Source is the individual data document (either XML or CSV) that populates the Product Catalogue via a Feed. Data Sources can be either Remotely defined or Uploaded manually. A Remote Source is a Data Source that is made available from a Merchants web server.
  • XML (Extensible Mark-up Language) is a general-purpose markup language. It is classified as an extensible language because it allows its users to define their own tags. Its primary purpose is to facilitate the sharing of data across different information systems, particularly via the Internet.
  • An XSD (XML Schema Document) describes how an XML document should be structured, what data types are permissible and the ranges of those data types. An XSD document can be used to validate that a particular XML document is structured correctly.
  • XSLT (Extensible Stylesheet Language Transformation) is designed to transform XML documents into other XML or “human-readable” documents. The original document is not changed; rather, a new document is created based on the content of an existing one.
  • CSV (Comma Separated Value) (also known as a comma-separated list or comma-separated variables) file format is a file type that stores tabular data. The format dates back to the early days of business computing. For this reason, CSV files are common on all computer platforms.

Product Data

The Product Catalogue is stored in a centralised database and regularly populated with Merchant product data from various sources.

Merchant data is organised into Feeds, each Feed is a distinct group of product data, for example a Feed could contain your entire inventory, seasonal sale offers or just a subset of best sellers. Feeds are populated with data identified through Data Sources. Each individual Feed can have any number of Data Sources.

Data Sources are added to Feeds and identify where data for that feed will be sourced as well as how often that data should be refreshed. Data can be delivered through a source as either XML or CSV (these are explained in more detail later in this document).

pfeeds-1

Data Sources

Data Sources identify where Feed data will be sourced. Data can be sourced as XML or CSV documents. You can upload data documents on a regular schedule directly from your web server or upload a single document on an ad-hoc basis.

Which source format you use, be it XML or CSV, is a decision that may be dictated more by your current data systems rather than preference. We would suggest, where you have the option, that you use XML as your preferred data source. XML offers the highest level of flexibility, validation and support and there are distinct advantages in using an XML data source rather than CSV. Some of the advantages you can derive from using XML are listed below.

  • XML validation (via XSD). You can ensure the data you are adding to the Product Catalogue is correctly formatted and valid.
  • Data transformation. If your XML isn’t structured as we require we are able to transform this into the correct format using an XSLT, this isn’t possible if you are supplying us with a CSV document.
  • Future proof. Your XML data will be future proof against additional constraints and attributes.
  • Error reporting. Where there are problems with your XML document we are able to provide more concise error reporting than with a CSV document.

SKU (Stock Keeping Units)

It is critical that each product you add to the Product Catalogue has an SKU. Products without an SKU will be rejected when imported. As products are imported into the Product Catalogue individual products are identified by their SKU and if the item already exists in the database it is replaced otherwise it is treated as a new product.

The SKU must correspond to a unique product; for example, if you add a kettle with an SKU of ABC123 to your Feed then a week later add a toaster with an SKU of ABC123 both products will be treated as the same product.

Uploading Data (Ad-Hoc)

When uploading data to a Feed via the Ad-Hoc document uploader in the Data Source screen, this data is treated exactly the same as a scheduled remote with the exception that the data is only added a single time and cannot be scheduled.

Error reports are available via the Feed Import Reports screen and an email will be sent to the recipient defined in the Feed should there be any problems uploading items to the Product Catalogue.

Categories and Attributes

Categories

Product Catalogue Categories are structured in a parent/child hierarchy. It is a requirement of your Data Source that each product is assigned to at least one category. If your products are not already assigned to categories in your database please contact your Account Manager for instructions on using a default category.

When notating a category structure in your feed document it is important that this is done accurately. Categories should be specified as a pipe separated string, i.e. if specifying in XML you would use:

Root|Jewellery|Men|Cufflinks

Root|Jewellery|Men|Watches

Please note the Root at the start of the category string, and that there is no pipe at the end of the string.

Attributes

Attributes are simply properties of a given product, such as sizes, colours, dimensions etc.

We have created a pre-defined list of common attributes which you can populate and also 5 “free-text” attributes:

See the list of available fields 

Products can use as many of these attributes as you wish.

XML, XSLT and XSD

Submitting your Data Sources as XML documents offers you the greatest level of flexibility in managing your Feed and maximising the exposure and effectiveness of your inventory. Optimise XML Data Sources need to be structured as per RSS 2.0 specification. RSS is simply a standardised structure (or schema) used to syndicate data across web sites and as such should be familiar to developers. We have extended the RSS specification with the “omg” namespace.

If you have an existing XML feed we can usually translate this into our format. Please contact your Account Manager to discuss this.

XML Schema (XSD)

We have made available an XML Schema Document (XSD) for you to use to build your XML output to our requirements, you can find this at http://feeds.omgpm.com/ns/1.0/import.xsd.

Your XML Data Sources should comply to this schema otherwise you will encounter difficulties importing your sources into the Product Catalogue.

The following list details the requirements of each node in your XML document. You can find a sample XML Data Source document at http://feeds.omgpm.com/ns/1.0/sample.xml.

SAMPLE FEED HERE

Entity escaping

Your data document must be UTF-8 encoded (you can generally do this when you save the file). As with all XML files, any data values (including URLs) must use entity escape codes for ampersands (&), single and double quotes (‘ and “), greater than (>) and less than (<) signs. You should also use numeric character entities (such as Ö) for certain symbol or international characters and not their equivalent HTML predefined entity since this will not produce well-formed XML.

Channel node The channel node can contain the following elements, none of these elements are mandatory but may assist you if there are problems with the document and you need to reference back from an Import Report (explained later in this document).

All dates are referenced using ISO 8601 formatting.

Node Mandatory? Format Description
pubDate Yes yyyy-mm-ddThh:mm:ss The date and time of this document’s creation. Document processing is skipped if the document date is not different from the previous Data Sources document date.
title Yes String (100) A title for this feeds document.
link Yes String (200) A URL reference for the document.
description Yes String (250) A brief description of the documents contents.
language Yes character RFC 1766 standard The principle language of the document, default en-gb.
copyright Yes String (250) A brief copyright declaration.
processCount Yes Integer The total number of items in this document, this number will be used to check that the correct number of items has been transferred to the Product Catalogue database when imported.

Within the channel node you may also have an unlimited number of items. An item is a single product from your inventory.

Please note the omg: namespace declaration above, please ensure that this declaration is added to the appropriate nodes and elements as indicated in the Item list below. It is also worth remembering that XML is case sensitive so an element called is different to an element called .

Item node

Your XML document can contain an unlimited number of Item nodes.

See the list of nodes

CSV (Comma Separated Values) Documents

Comma separated documents are documents that have their fields separated by a “delimiter” and in the case of CSV this is a comma. If you would like to use a different delimiter such as Pipe | or Tab we can also support these. All string columns should have an additional speech mark qualifier (“).

A sample CSV document can be found at http://feeds.omgpm.com/ns/1.0/sample.csv.

Items stored in CSV documents are stored 1 item per row and for this reason it is not possible to represent more than one category or attribute per item. You should use the first row of your CSV document to display the column headings as shown in the table below. If you enter product data into the first row or leave the first row empty the CSV import will fail.

The same product fields are available in a CSV document as are in an XML document, these are listed below.

Available Fields

Parameter Data Type Mandatory? Description
ProductSKU String Yes Product SKU provided by the Merchant
ProductName String Yes Product Name
ProductDescription String Yes Product Description – this may contain formatting provided by the Merchant
ProductPrice Decimal Yes  Product Price
ProductPriceCurrency String Yes Product Price Currency as 3 digit ISO standard value. eg. GBP, USD, INR
DiscountedPrice Decimal No The Product Price with any discount applied
WasPrice Decimal No The Previous Price of the product before any discount was applied
ProductURL String Yes The Deeplink URL of the product
PID Integer Yes Optimise PID
MID Integer Yes Optimise Merchant ID
ProductSmallImageURL String No URL to small product image
ProductMediumImageURL String No URL to medium product image
ProductLargeImageURL String No  URL to large product image
MPN String No Manufacturer Part Number
StockAvailability String No Indicates whether item is in stock or not
Brand String No Brand associated with product
Colour String No Colour of the product
Location String No Location of the product such as with a Daily Deal
Custom1 String No Free text custom field
Custom2 String No Free text custom field
Custom3 String No Free text custom field
Custom4 String No Free text custom field
Custom5 String No Free text custom field
CategoryName Numeric Yes Category Name as supplied by the Merchant
CategoryPathAsString Numeric Yes Full Category Path

Feed Manager

The Feed Manager allows you to manage the Feeds that deliver data into the Product Catalogue. You can create as many Feeds as you wish.

The Feed Manager allows Merchants to control the following aspects of their feed:

  • Temporarily suspend feed delivery to Affiliates
  • Assign the recipient (email) of the person who will receive import error reports
  • Assign products in the feed to a default Programme (allowing you to pay different commissions on a per-feed basis). You can also assign individual products to an Optimise Programme, please contact you Account Manager for more help.
  • View snapshot information about product counts, last imports and Data Sources

FAQs

  1. What happens when I remove an item from the Product Catalogue, will affiliates still see it?
    No affiliates will not see the item, all updates are made in real time.
  2. How will access to feeds be managed?
    Product feed access will be managed and controlled by the merchant and Account Manager. Campaign approvals will initially act as the gateway with additional control to be configured in the product feed interface.
  3. Will the UID/SubID parameter be passed in reporting?
    Yes the affiliate will be able to pass any UID/SubID into the URL that is generated.
  4. How should I format a date?
    Dates should be formatted as per ISO 8601 specifications.