AWIN Telco Datafeeds developer guidance

Index

Contact & Support

If you are experiencing difficulties downloading the latest data, interpreting the documentation or think you might have identified a bug or inconsistency in the data, please don't hesitate to get in touch with Publisher Services:

Important notes

In general all products will be better described, and in more detail in the JSON Telco fields.

Generic / Default fields

These fields are available across all verticals and should be used by anyone wishing to include telco products alongside other types of product. Note that in order to provide data that can co-exist with far 'simpler' product types, the information in the generic / default fields is heavily simplified. Anyone planning to make extensive use of Telco products is encouraged to use the JSON Telco fields described later in this document.

aw_product_id

Affiliate Window's unique product ID

merchant_product_id

A unique ID linked to this deal. The unique ID persists from one feed to the next, including in most cases, when monthly or upfront prices change.

merchant_category

The primary product's product type. See the list of valid product types here.

aw_deep_link

This is the 'tracked' version of the merchant_deep_link field. You should use this to ensure you receive commission for your clicks. Where a basket/deep link is unavailable, the product page link will automatically be substituted here.

merchant_image_url

A large (400x400 pixels) image of the primary product being sold.

Note: This image will have a white background. Should you want a large image with a transparent background, consider using the large_image field instead.

A note about images.

search_price

The deal's upfront price. This is a one-off price. See store_price

description

The primary product's product description. Usually a paragraph or two long, and designed to act as an introduction to the product's main features and benefits for anyone browsing your product page.

Example

The 4G ready Galaxy S5 has all the iconic design you'd expect from Samsung. The perforated pattern on the back cover creates a sleek modern look and the contoured shape comes in a range of colours including Charcoal Black, Shimmery White, Electric Blue and Copper Gold. Dust and water resistant, the S5 is made to last. With an IP67 certification, the S5 is resistant to sweat, rain, liquids, sand and dust so your phone is protected whilst you enjoy your favourite sporting activities. Packed with an impressive 16 megapixel camera with selective auto focus and advanced High Dynamic Range for beautifully lit shots even in low light conditions.

Note: Where the network does not contain "No Network", this field should be consistently populated. Developers should not make assumptions about the availability or completeness of product descriptions under other circumstances.

product_name

Describes the primary features of the deal being sold.

Example

Samsung Galaxy Note 3 (White) on O2 O2 Refresh 4G (24 Month(s) contract) and 500 mins UNLIMITED texts 500MB 4G Internet data for 33.00 per month

merchant_deep_link

the merchant's untracked basket URL (or the 'deepest' URL available for this merchant). You should only use this URL if you plan on adding your own tracking links.

aw_image_url

A medium (200x200 pixels) image of the primary product being sold (served from Affiliate Window's servers).

Note: This image will have a white background. Should you want a large image (though larger, at 400x400 pixels) with a transparent background, consider using the large_image field instead.

A note about images.

merchant_name

The trading name of the merchant whose products are represented in this datafeed.

merchant_id

A unique ID for the merchant mentioned above.

category_name

Affiliate Window's product category for the primary product represented on any given row of the feed.

delivery_cost

currency

The only currency currently supported is "GBP"

store_price

This is the deal's upfront cost. The upfront cost usually relates to the purchase of a device with a contract (contracts on their own, for instance SIM-only will rarely if ever attract an upfront cost). Note that in some cases, the device and the linked contract can have separate monthly costs. Where this is the case, details can be found in the deal_cost_json field.

display_price

This joins the currency and store_price fields together.

data_feed_id

Affiliate Window's unique ID for the specific datafeed that any given row belongs to.

rrp_price

specifications

The primary product's specifications, represented as a name:value pair, with each specification separated by an asterisk. You can feel free to interpret this field programmatically as it will always remain structured in this way.

Example

* Colour: Gold * SIM Type: Micro SIM * Camera Megapixels: 16 * Camera Flash: LED * Selfie Camera: 2.1 Megapixel, 1080p@30fps * Screen resoution: 1080 x 1920 * Screen size: 5.1" * Screen type: Super AMOLED capacitive touchscreen, 16M colors * Internal memory: 16GB * Memory card slot: microSD, up to 128GB * Processor: 2.5 GHz Quad-core Krait 400 * Chipset: Qualcomm Snapdragon 801 * Cellular support: 2G 3G 4G * Maximum Talk-time: Up to 21 hours * Bluetooth: 4.0 with A2DP, LE, EDR * GPS: A-GPS and GLONASS * Wifi: 802.11 a/b/g/n/ac, dual-band, DLNA, Wi-Fi Direct, Wi-Fi hotspot * Weatherproofing / IP Rating: IP55 & IP58 - Protected against dust, water jets and immersion in water * Weight (grams): 144 * Dimensions: 142 x 72.5 x 8.1 mm * Operating System: Android

Usage

Notes

condition

Whether the primary device (i.e. not including free gifts) is "new" or "refurbished" (these are the only two valid values and will always appear lowercase). Note that some merchants or brands may prefer to have their products described differently (for instance EE prefer to use "Good as new" to describe refurbished products whereas Apple prefer "Refreshed". Where this is the case, you can find the appropriate brand-friendly representation in the device_features_json field under condition_friendly.

promotional_text

Any promotional text that relates to the deal, should any exist. It is expected that this text would be passed through as is and displayed on site. Often this text describes some important aspect of the deal and so it is important that it is displayed to consumers in order for them to be fully informed and improve both chances of click-through and ultimately conversion.

warranty

This field is currently unused.

Note: All new products sold in the UK will have a minimum 1 year warranty and are covered by both EU directive 1999/44/EC (which states that all EU countries have to ensure a retailer could be held liable for all "non-conformities" which manifest within two years from delivery) as well as the UK's SOGA (Sale Of Goods Act).

merchant_thumb

A small (150x150 pixels) thumbnail image of the primary product being sold.

Note: This image will have a white background. Should you want an image with a transparent background, consider using the alternate_image field instead.

A note about images.

aw_thumb_url

A very small (70x70 pixels) thumbnail image of the primary product being sold.

Note: This image will have a white background. Should you want a (slightly larger 150x150 pixels) thumbnail image with a transparent background, consider using the alternate_image field instead.

A note about images.

brand_name

The primary product's branding. Note that this could be different from the manufacturer, so for instance a "Google Nexus 6" is branded "Google" but is manufactured by Motorola. Wherever possible we will specify the branding rather than the manufacturer. Similarly the "EE Kestrel" is manufactured by Huawei, but will be branded "EE" in our data.

brand_id

Affiliate Window's unique ID for this brand

delivery_time

valid_from

valid_to

web_offer

This field contains details of any bundled benefits, gifts or promotions that come with the deal. Note that this is a very simple, asterisk-delimited representation. A significantly more detailed and structured representation of this data is available in the field: deal_extras_json

Example

*BlackBerry Services *O2 Priority *O2 Tracks *O2 TU Go *O2 WiFi Hotspots *O2 Travel

Note: This field will be empty if the network field contains "No Network" and can be ignored.

pre_order

Boolean - Contains 1 if the the device is available for pre-order only, or 0 if the device has some other stock status (could be in stock or out of stock).

in_stock

Boolean - Contains 1 if in stock, otherwise 0.

stock_quantity

is_for_sale

This field will always be set to 1 (you can assume that if it appears in the feed, it's available for sale). 

product_type

Describes the type of deal (Consumer, Upgrade, Business, etc) to allow appropriate filtering. Currently valid values are described here.

commission_group

upc

ean

mpn

isbn

model_number

This is the primary product's full name, excluding the manufacturer/branding. You can prefix the brand_name field to this field to construct a full product name.

Example

iPhone 5c White 8GB

parent_product_id

language

Currently the only supported language is 'English'.

last_updated

This is the date/time the deal described in this row was last imported by our systems. 

dimensions

The primary product's dimensions - always in the format "H x W x D mm". Dimensions are not always available for all product types (SIM Cards being one example). See Specifications and Features availability for more information.

colour

This is the device's "Colour Group". We use this for grouping or filtering, and as such the list of acceptable values here has been reduced to a sensible minimum. You won't find any "ruby red" or "sunset orange" style values here, just "red" and orange".

This data is repeated in the device_features_json field described later in this document, along with a list of valid values.

The colour won't always be available (for SIM Cards, for instance). See Specifications and Features availability for more information.

keywords

This field will be populated with the word 'exclusive' in the case of affiliate channel or publisher exclusives.

custom_1

Contains the retailer logo URL, to be used for linking out to their site or in comparison lists.

custom_2

Contains the URL for the Retailer's general terms and conditions page. Note that this differs from the Network's terms and conditions page found in network_details_json.

custom_3

This contains the type of contract being sold to the customer. These values can be used to reliably filter/group tariffs. See tariff_details_json for a list of valid values.

custom_4

Contains the URL for the primary device's product page on the merchant's website, where available. In most cases, the deeplink URL is better for conversion.

custom_5

Contains an asterisk-delimited list of cash discounts. These are broken down below:

Notes

custom_6

Contains the Brand-friendly description for the Data Allowance. In all cases, this field will repeat what you see in inc_data while overriding any content that isn't On-Brand. You can therefore rely on this field for display purposes without having to check both fields, but always use the inc_data field for comparison/sorting/filtering.

Note: This is often a legal/compliance issue and it is thus important that this value is used in your presentation layer when engaging with customers. The underlying data allowance is still contained in the inc_data field and should still be used for comparison/sorting/filtering purposes.

saving

delivery_weight

delivery_restrictions

reviews

average_rating

number_stars

number_available

rating

alternate_image

The primary device's thumbnail image, 200x200 pixels with transparent background. A note about images.

large_image

The primary device's large image, 400x400 pixels with transparent background. A note about images.

basket_link

This will contain only basket links. Unlike the aw_deep_link field described earlier, product page links won't be substituted in where basket links are unavailable.

Simple Telco fields

The fields listed above form part of the Affiliate Window "Generic" schema. The fields below, however, are only available if the user elects to enable the additional "Telco" fields, which we highly recommend. The intention is that the fields below will enhance the information available to users of the generic schema without much additional work.

contract_type

See tariff_details_json for a list of valid values.

term

The number of months this contract runs for.

Note: This field will contain the length of the handset finance agreement term where the deal is a giffgaff deal. Since giffgaff are a pay-as-you-go network, there's no term associated with the tariff portion of the deal.

Note 2: Some Networks for legal reasons don't advertise "1 month" contracts and instead refer to "30 day" contracts. Any brand-friendly contract length descriptions can be found in the tariff_details_json field under tariff_term_friendly.

initial_cost

See search_price earlier in this document. Far more detailed pricing information is available in deal_cost_json.

month_cost

This is the deal's total monthly cost. Note that in some cases, the phone and contract are sold separately, with a finance agreement covering the device's monthly cost, and a separate contract governing the services provided by the Network. Details of these 'split' monthly pricing deals (of which O2's Refresh tariffs are one example) can be found in the more detailed deal_cost_json field. In all cases, even where the monthly cost is split, this (month_cost) field will represent the sum of the device and contract monthly costs.

Note: This field will be empty if the network field contains "No Network". Otherwise you can rely on it being populated.

gift

inc_minutes

Contains the total number of cross-network, anytime minutes available with this contract. Some or all of these minutes may be eligible for use abroad. Where this is the case it will only be described in the more detailed tariff_allowances_json field described later in this document.

Note: This field will be empty if the network field contains "No Network" or if the tariff type being sold doesn't include a minutes allowance.

inc_texts

Contains the total number of anytime texts available with this contract. Same-network texts are described in tariff_allowances_json

Note: This field will be empty if the network field contains "No Network" or if the tariff type being sold doesn't include a texts allowance.

inc_data

Contains the total amount of data included in this contract, expressed as a number of megabytes. This excludes any WiFi allowances that might be described in the more detailed tariff_allowances_json field.

Note: This field will be empty if the network field contains "No Network" or if the tariff type being sold doesn't include a data allowance.

IMPORTANT NOTE: This field can be used reliably for sorting/filtering/grouping, but please refer to the custom6 field for the Brand-friendly description of any data allowances included in this deal. This can be important for legal/compliance reasons and so should not be skipped.

connectivity

Describes the fastest 'speed' at which the contract will allow the customer to access data services. Currently available values are:

Notes

tariff

A short text description of the Network contract being sold.

Note: This field should be ignored if the network field contains "No Network"

storage_size

Describes the primary device's storage capacity rounded to the nearest GB. This field is intended to be used for filtering/grouping similar products and may not be available in all cases. See Specifications and Features availability for more information.

special_offer

network

The Mobile Network Operator's brand name. Will be set to "No Network" in the case of products not sold with a contract.

operating_system

The primary device's operating system, where known (USB Modems for instance are unlikely to have an Operating System listed). See Specifications and Features availability for more information.

JSON Telco fields

These fields should be used in preference to the others described earlier in this document wherever possible. Through a more complex structure we are able to more accurately represent the industry's available deals and so better communicate them to customers, leading to improved conversion.

Note: The following (default / generic) fields should be downloaded alongside all the below fields as they aren't duplicated here:

Note: Not all the fields described below contain JSON, though they are listed here as they are expected to be used alongside the JSON fields. JSON-containing fields can be identified in create-a-feed by the presence of a _json field-name suffix.

device_product_json

The "product" sits at the highest level of our product tree, and describes a conceptual product like an "iPhone" or a "Galaxy" phone. It belongs to a manufacturer/brand, and has a product type. Using the product_id you can group all "Galaxy" products together or all "iPhone" products together (for example).

Example (Nokia Lumia 735 Black):

Contains

Current product_type values

The product_name can be appended to the product_brand to arrive at a more complete product name: product_brand + product_name = "Apple iPhone".

device_product_version_json

The "product version" sits below the "product" in the product hierarchy and describes at a reasonably high level the product in the range. Examples would be (Apple iPhone) "5s" or (Samsung Galaxy) "S4". Using the product_version_id, all the different colours and capacities of Samsung Galaxy S4 could be grouped together, or we can filter on just Apple iPhone 5C, and see all the colours and capacities that are available.

Example (Nokia Lumia 735 Black):

Contains

The product_version_name can be appended to product_name and product_brand to arrive at the complete product version name: product_brand + product_name + product_version_name = "Apple iPhone 5S".

device_product_edition_json

The "product edition" is the lowest level of the product hierarchy and describes a specific product being sold. Examples would be (Apple iPhone 5S) "16GB White" or (Samsung Galaxy S4) "32GB Blue". The product edition ID is therefore unique to each specific product unlike the product_version_id and product_id.

Example (Nokia Lumia 735 Black):

Contains

Note that in practice, the capacity and colour will act as the defining features of this edition (separating it from other editions under the same product_version), but in future other defining features could emerge. Note also that the capacity and colour are described in a structured way in the device_features_json field so there is no need to parse the product_edition_name field.

The full product name can be derived by using the product_brand, product_name, product_version_name and product_edition_name together: e.g. "Apple iPhone 5S 16GB White", though this has been provided in the next field.

device_full_name

Should always be the same as adding together product_brand, product_name, product_version_name and product_edition_name.

device_description

The primary product's product description. In all cases where the network_details_json.company_id field is not "76" (i.e. a telco product sold on contract), this description should be fully populated. Developers should not assume the existence of a complete description under other circumstances.

device_images_json

Example

Contains

More image types could be added in future. A note about images.

device_features_json

This field contains product attributes that can be used for filtering and grouping of products.

Example

Contains

Note that unless marked otherwise with above, the values can be empty for product types where the feature does not apply (for instance Televisions don't have a SIM Card Type), and as a result the key may not appear. See Specifications and Features availability for more information.

Valid colour_group values

device_specifications_json

It is expected that specifications will not be used for filtering or grouping, in particular because many of the specifications are free text fields, however where values are likely to be consistent, this has been indicated below.

Example

Contains

Note that many of the fields below have already been described here and so aren't repeated below. Those fields that are unique to the JSON representation have been described.

Note: While the device_specifications_json field will exist in all cases, the values for the sub-fields could still be empty. Where this is the case, the key will not be included. This is because not all specification types apply to all products. See Specifications and Features availability for more information.

network_details_json

General details of the Mobile Network Operator with whom the customer will have a contract.

Example

Contains

Note: In cases where the product does not belong to a Network (i.e. is SIM-Free or not a cellular device), the name ("No Network") and company_id ("76") values will be populated consistently but the other values can be blank. See also Skipping fields based on network_details_json.

tariff_group_details_json

Tariffs are often grouped by the networks. The tariff group allows for filtering/grouping of tariffs. Similar tariffs often have the same benefits, call charges etc. See also Displaying tariff information.

Example

Contains

Note: In cases where the product is sold without a contract (as in the case of SIM-Free phones, or some wearable devices), the tariff_group_description field can be empty. In all other cases it should be populated. Where the product is sold without a contract, you should find that network_details_json.company_id is set to "76". See also Skipping fields based on network_details_json.

tariff_details_json

Contains details of the specific tariff being purchased. See also Displaying tariff information.

Example

Contains

Valid values for tariff_type_id and tariff_type

Notes:

tariff_allowances_json

Contains details of all the allowances that come with this tariff. See also Displaying tariff information.

Example

Contains

mins_details

texts_details

data_details

Notes:

tariff_out_of_plan_charges_json

Contains details of pence-per-minute or pence-per-MB style charges when the customer uses up all their inclusive allowances (or where there's no inclusive allowance). See also .

Example

Contains

Notes:

deal_type_json

Describes the type of sale to allow appropriate filtering. Valid values are currently limited to:

Example

Contains

Currently valid values for deal_type_id and deal_type_name

JSON-Only: Currently valid values for deal_type_id and deal_type_name

deal_legal_info

This field may (it's not always populated) contain text that should be passed through unaltered and displayed on your web page. The text usually contains legally required information relating to the package being sold. See also Displaying tariff information.

Example

From 2015, Airtime Plan prices will be adjusted on your April bill by RPI rate of inflation announced in the preceding February. Phone Plan on 0% APR Representative, 24 month consumer credit agreement, subject to status and credit check. 18+

deal_promo_info

See also Displaying tariff information.

Should the deal have any promotional information tied to it, this will be displayed here. The text should be passed through unaltered where possible as it could contain important information about the customer's deal.

deal_extras_json

Extras are split into high-level Groups (like "Free Gifts", or "Discounts & Loyalty", for instance), and within those groups Extras are further sub-categorised into Source Types. Everything is given a consistent ID and so Groups and Types can be grouped/filtered as required within your code. See also Displaying tariff information.

Example

Contains

Extra Group Types:

Example Source Types:

Interpreting the groupingId:

Allowance type IDs:

Notes:

deal_retailer_json

Contains details of the merchant (retailer) selling the deal. Note that this can be different from the Network the deal is being sold on.

Example

Contains

deal_cost_json

Contains details of the deal's pricing both including and excluding VAT. Including VAT prices should be shown for consumer deals, whereas convention dictates that business-only deals be sold at exc. VAT prices. We have included both in case you need to mix and match business and consumer deals in the same list.

See Understanding Pricing for more information.

Example

Contains

Notes

deal_discounts_json

Details the discounts available with this deal, split into network and retailer discounts (the two can co-exist). A retailer discount is often supplied on a redemption (customer must claim) or automatic (sent in the post after x days) basis, and payment will usually arrive by cheque or bank transfer. By contrast a network discount is usually discounted at source, and so the customer will see the discount applied to their monthly bill.

See implementation tips on filtering/grouping. See also comparing with Cashbacks.

Example

Contains

network_discount

retailer_discount

Discount types (used in the above nd_reduction_type_id and rd_reduction_type_id fields):

Payment types (used in the above nd_payment_type_id and rd_payment_type_id fields):

Notes

deal_cashback_json

See implementation tips on filtering/grouping and comparing with Discounts.

Example

Contains

Note: This field will be empty where no cashbacks are available for this deal.

Implementation tips

These implementation tips can be used in conjunction with wireframes (here for PAYG and here for PAYM) that demonstrate the relative importance of various data elements through the use of colour and positioning.

Grouping and Filtering Devices

Should you wish to focus purely on the hardware, the merchant_category (generic) or device_product_json (JSON) fields provide basic product type categorisation, with the JSON fields in general providing a more reliable ID-based approach.

In many cases however, it's likely that you will want to also filter based on the type of contract (pay as you go, mobile broadband, sim only, etc.), as well as deal type (consumer, existing customer, upgrade, business, etc.) linked to the device in order to ensure the customer doesn't end up looking at a device only available on a type of contract they aren't interested in.

For deal type, check out the product_type (generic) or deal_type_json (JSON) fields, and details of the contract type are available in custom3 (generic) and tariff_details_json (JSON).

Sorting and Filtering Discounts

Discounts (whether network or retailer discounts) are represented identically aside from field naming. This means that both types of discount can be stored internally in the same table, with just a marker denoting whether the discount is a retailer or network discount. This should make filtering far easier.

The nd_reduction_type_id and rd_reduction_type_id fields described here can be used to group deals by the type of discount being offered, or perhaps more usefully, the fields can be used in combination with the _value and _duration_in_months fields to calculate the total discount available and use this derived value as a means of sorting the results (or comparing against Cashbacks - see "Filtering and Grouping Cashbacks" below).

Using the _payment_type_id field, developers can group deals according to whether or not the customer is required to redeem the discount, or whether it is automatically applied. In many cases customers will prefer to opt for an automatically applied discount.

Filtering and Grouping Cashbacks

Cashbacks are really just a simpler type of discount where the amount of discount is expressed as a total discount available. This means Cashbacks can be compared directly against Discounts in two ways:

Understanding pricing

Many will be used to the idea of pricing in the Telco vertical being split into an upfront cost (a deposit of sorts on the hardware, assuming we aren't dealing with a SIM-only deal) and a monthly cost that covers the service/allowances being purchased but also subsidises the cost of the device.

While the above approach still exists, there are now more complex pricing structures being adopted that not only have a bearing on the data now made available via datafeeds but also on how pricing is displayed on the web. In many cases there can be legal requirements that have to be met (such as displaying information about RPI-linked price increases or credit agreements) and pricing is now increasingly represented as one price for the service, and another for the handset or device. Additionally the contract term for the device and service can be different (so for instance Giffgaff offer 30 day topups, and hire purchase agreements for the device of up to 24 months)

When should I use ex. VAT pricing?

If the deal is a Business deal (product_type (generic) or deal_type_json (JSON) fields), then you should use ex. VAT pricing wherever possible. It is acceptable to use inc. VAT pricing in circumstances where Consumer and Business deals are being compared but you should indicate clearly that the customer will be charged Ex. VAT when it comes to payment.

How will I know when to show separate monthly prices for devices and tariff?

For comparison / sorting / filtering purposes you can safely just use the upfront_inc_vat / upfront_exc_vat and monthly_total_inc_vat / monthly_total_exc_vat fields. It's only when it comes to displaying pricing for the deals in question that you need to worry about any split.

Identifying a deal where the price has been split is straightforward - if monthly_device_inc_vat / monthly_device_exc_vat is populated, then we're dealing with a split-pricing deal. Remember that the contract length for the device (monthly_device_term_months) can be different from the contract length for the service/tariff (monthly_contract_term_months), so you'll need to ensure these are properly represented on the page along with the legal text if populated.

I'm not using the JSON fields. How can I implement split-pricing?

This is currently unsupported. Split pricing information is only available here. Even if you aren't able to use JSON natively in your code, it may be possible to extract the required values using some simple regular expressions, though the exact method will depend on your programming language of choice.

Displaying tariff information

Note that this section assumes the use of JSON fields. When displaying a deal, the following should be considered:

A note about images

We attempt to ensure that images are provided in all cases however there are some situations beyond our control (for instance early product pre-orders) that mean images won't always be available. Where that's the case we will always provide a placeholder image so your import code won't throw errors and your web page won't contain any broken image links. As soon as we are able to get hold of the relevant image, the feed will be updated to include it.

In total there are six styles of image available, listed below:

Note: The large_image and alternate_image data is repeated in the device_images_json field.

Handling feed updates efficiently (JSON only)

Since the JSON fields are structured and include IDs wherever possible, we can rely on them to efficiently update the feed whenever it is imported. Rather than overwriting everything in your local database each time you import a row of the CSV you can check each ID just once, and then ignore any further occurrences of it in the feed.

For a super-quick import you can even just check *some* of the fields as described below, though you risk not picking up on corrections to previously faulty data (human errors will always happen). If you do want to use this approach we recommend that you perform a more complete update once every couple of days or so.

Bare minimum field value updates

During each feed import run, assuming the IDs (and previously imported data) for the below already exist in your database:

Skipping fields based on network_details_json

Where the network_details_json.company_id is "76", we're dealing with a product that comes without a contract. Therefore we can skip the following fields, which will be unused in this context:

Specifications and Features availability

In all cases where the product is a "Mobile Phone" (device_product.product_type_id = "1"), all of the fields mentioned below should be populated.

Where the product type is not a Mobile Phone, you should check each field carefully for a value without assuming they will always be available.