Product Feed

You can provide the product feed file in CSV format.

Set up

The feed is configured through AppManager -> Build -> Feed. The configuration defines source file, schedule, product deletion and feed comparison.

Configuration

The image above shows the feed configuration interface. Explanation of the fields:

• Feed name - User-defined name of the feed configuration
• Feed URL - URL to the source feed CSV file.
• Feed type - Product or Category
• Feed comparison - This setting enables faster feed processing when the files are similar. Note that this feature compares the previous feed file to the current one. Missing products are deleted, updated products are updated, and new products are added as expected.
• Feed cleanup - This setting enables tracking of feed runs. It keeps a list of products and listings defined in the file. When enabled it deletes all products and listings that are not present in the new feed file. The setting is useful when the feed file completely changes the catalogue.
• Frequency - Defines the weekdays and hour to run the import from the feed file - This setting gives predictable execution, so third-party system can update the source file before imports.

Product Feed Specification

Product Feed Example

Below is an example CSV that will create a single Product; a T-Shirt. The Product has two forms; colour, and size. The Product has three Product Variants; White Small, White Medium, and White Large. The feed file example can be downloaded here.

product-id,variant-id,listing-id,name,forms,form-id_colour,form-value_colour,form-swatch_colour,form-id_size,form-value_size,price-now_GBP_GB,price-was_GBP_GB,price-now_EUR_FR,available,low-on-stock,max-orderable-quantity,quantity,barcode,video-url,image_0,image_1,default-variant-id,brand,description,description-raw,web-url,link-title_0,link-url_0,link-title_1,link-url_1,promotion-badge_0,promotion-message_0,category-id_0,category-id_1,review-rating,review-count,filter-attr-name_0,filter-attr-value_0,Gifting-Available,Gift-Id
1,001-001,1,T-Shirt,"colour,size",colour_White,White,https://cdn.shop.com/colorimages/White.png,size_Small,Small,55.95,85.95,65.95,TRUE,FALSE,5,20,001-001,https://cdn.shop.com/001-001.mp4,https://cdn.shop.com/images/001_001a.png,https://cdn.shop.com/images/001_001b.png,001-001,Cool Shirts,This is a cool shirt.,<p>This is a cool shirt.<p>,https://www.shop.com/products/001,Size Guide,https://cdn.shop.com/sizeguide.html,Delivery Information,https://cdn.shop.com/delivery.html,Sale,Buy One Get One Free,clothing,cool,5,100,Style,Cool,TRUE,001-001
1,001-002,1,T-Shirt,,colour_White,White,https://cdn.shop.com/colorimages/White.png,size_Medium,Medium,55.95,85.95,65.95,FALSE,TRUE,5,0,001-002,https://cdn.shop.com/001-002.mp4,https://cdn.shop.com/images/001_002a.png,https://cdn.shop.com/images/001_002b.png,,,,,,,,,,,,,,,,,,TRUE,001-002
1,001-003,1,T-Shirt,,colour_White,White,https://cdn.shop.com/colorimages/White.png,size_Large,Large,55.95,85.95,65.95,TRUE,FALSE,5,20,001-003,https://cdn.shop.com/001-003.mp4,https://cdn.shop.com/images/001_003a.png,https://cdn.shop.com/images/001_003b.png,,,,,,,,,,,,,,,,,,TRUE,001-003

The above feed file will produce a Product with the following JSON Structure. The JSON file output can be downloaded here.

{
  "CategoryIds": [
    "clothing",
    "cool"
  ],
  "Details": {
    "Name": "T-Shirt",
    "Brand": "Cool Shirts",
    "Description": "This is a cool shirt.",
    "DescriptionRaw": "<p>This is a cool shirt.</p>"
  },
  "Forms": [
    {
      "Name": "colour",
      "Preselected": true,
      "Variations": [
        {
          "Id": "colour_White",
          "Value": "White",
          "Swatch": "https://cdn.shop.com/colorimages/White.png"
        }
      ]
    },
    {
      "Name": "size",
      "Preselected": false,
      "Variations": [
        {
          "Id": "size_Small",
          "Value": "Small"
        },
        {
          "Id": "size_Medium",
          "Value": "Medium"
        },
        {
          "Id": "size_Large",
          "Value": "Large"
        }
      ]
    }
  ],
  "id": "001",
  "Meta": {
    "DefaultVariantId": "001-001",
    "Links": [
      {
        "Title": "Size Guide",
        "Url": "http://cdn.shop.com/sizeguide.html"
      },
      {
        "Title": "Delivery Information",
        "Url": "http://cdn.shop.com/delivery.html"
      }
    ],
    "WebUrl": "https://www.shop.com/products/001"
  },
  "Promotion": {
    "Badges": [
      "Sale"
    ],
    "Messages": [
      "Buy One Get One Free"
    ]
  },
  "Review": {
    "Rating": 5.0,
    "Count": 100
  },
  "Variants": {
    "001-001": {
      "Id": "001-001",
      "Forms": {
        "colour": {
          "Id": "colour_White",
          "Value": "White",
          "Swatch": "https://cdn.shop.com/colorimages/White.png"
        },
        "size": {
          "Id": "size_Small",
          "Value": "Small"
        }
      },
      "Images": {
        "Default": [
          "https://cdn.shop.com/images/001_001a.png",
          "https://cdn.shop.com/images/001_001b.png"
        ]
      },
      "ListingId": "001",
      "Meta": {
        "Barcode": "001-001",
        "videoURL": "https://cdn.shop.com/001-001.mp4",
        "DefaultCurrency": "GBP_EN"
      },
      "Name": "T-Shirt",
      "Prices": {
        "GBP_EN": {
          "Now": 55.95,
          "NowFormatted": "£55.95",
          "Was": 85.95,
          "WasFormatted": "£85.95",
          "CurrencySymbol": "£"
        },
        "EUR_FR": {
          "Now": 65.95,
          "NowFormatted": "€65.95",
          "Was": 85.95,
          "WasFormatted": "€85.95",
          "CurrencySymbol": "€"
        }
      },
      "Stock": {
        "Available": true,
        "LowOnStock": false,
        "MaxOrderableQuantity": 5,
        "Quantity": 20
      },
      "CustomData": {
        "Gifting-Available": "true",
        "Gift-Id": "001-001"
      }
    },
    "001-002": {
      "Id": "001-002",
      "Forms": {
        "colour": {
          "Id": "colour_White",
          "Value": "White",
          "Swatch": "https://cdn.shop.com/colorimages/White.png"
        },
        "size": {
          "Id": "size_Medium",
          "Value": "Medium"
        }
      },
      "Images": {
        "Default": [
          "https://cdn.shop.com/images/001_002a.png",
          "https://cdn.shop.com/images/001_002b.png"
        ]
      },
      "ListingId": "001",
      "Meta": {
        "Barcode": "001-002",
        "videoURL": "https://cdn.shop.com/001-002.mp4",
        "DefaultCurrency": "GBP_EN"
      },
      "Name": "T-Shirt",
      "Prices": {
        "GBP_EN": {
          "Now": 55.95,
          "NowFormatted": "£55.95",
          "Was": 85.95,
          "WasFormatted": "£85.95",
          "CurrencySymbol": "£"
        },
        "EUR_FR": {
          "Now": 65.95,
          "NowFormatted": "€65.95",
          "Was": 85.95,
          "WasFormatted": "€85.95",
          "CurrencySymbol": "€"
        }
      },
      "Stock": {
        "Available": false,
        "LowOnStock": true,
        "MaxOrderableQuantity": 5,
        "Quantity": 0
      },
      "CustomData": {
        "Gifting-Available": "true",
        "Gift-Id": "001-002"
      }
    },
    "001-003": {
      "Id": "001-003",
      "Forms": {
        "colour": {
          "Id": "colour_White",
          "Value": "White",
          "Swatch": "https://cdn.shop.com/colorimages/White.png"
        },
        "size": {
          "Id": "size_Large",
          "Value": "Large"
        }
      },
      "Images": {
        "Default": [
          "https://cdn.shop.com/images/001_003a.png",
          "https://cdn.shop.com/images/001_003b.png"
        ]
      },
      "ListingId": "001",
      "Meta": {
        "Barcode": "001-003",
        "videoURL": "https://cdn.shop.com/001-003.mp4",
        "DefaultCurrency": "GBP_EN"
      },
      "Name": "T-Shirt",
      "Prices": {
        "GBP_EN": {
          "Now": 55.95,
          "NowFormatted": "£55.95",
          "Was": 85.95,
          "WasFormatted": "£85.95",
          "CurrencySymbol": "£"
        },
        "EUR_FR": {
          "Now": 65.95,
          "NowFormatted": "€65.95",
          "Was": 85.95,
          "WasFormatted": "€85.95",
          "CurrencySymbol": "€"
        }
      },
      "Stock": {
        "Available": true,
        "LowOnStock": false,
        "MaxOrderableQuantity": 5,
        "Quantity": 20
      },
      "CustomData": {
        "Gifting-Available": "true",
        "Gift-Id": "001-003"
      }
    }
  },
  "CustomData": {
    "Gifting-Available": "true",
    "Gift-Id": "001-001"
  }
}

Product Feed Deep Dive

This section provides a closer look into some of the properties that can be supplied in the product feed, and how they will impact the app experience.

Availability

The available field can be supplied to indicate that a Product Variant is not available for purchase. Users will not be able to add them to their cart:

Categories

Categories that each product belongs to can be defined via the category-id_[index] field. [index] should be substituted with a zero-based numerical index. For example; category-id_0, category-id_1.

Products are associated to the category with the matching ID. Products associated to a category will be displayed in the Product Listing Page when viewing the category.

Custom Data

Product data can be enriched to include extra data that can be used to power customisations in the App. For example, some products may have some gifting options to select from, which can be provided via Custom Data. Custom Data is included at both the Product and Product Variant level. The first Product Variant in the feed will have its Custom Data stored at both the Product and Product Variant levels. Product Variants that follow the first will only have their Custom Data at the Variant level.

Filters

Filters appear in the Product Listing Page when Poq's Search Service is enabled. They allow for filtering of Search results. More information on filters can be found in the Search Context Documentation.

Forms

Product Forms can be supplied for Products that have multiple Product Variants. Forms define the properties by which each variant can differ. For example, a T-shirt may have Size, Colour and Fit forms, A Product Variant is an instance of the Product with a distinct variation of these forms. For example a medium green loose fit T-Shirt.

Other examples may include:

• A 128GB Space Gray iPhone (Disk Space & Colour Forms)
• An A3 Black Wooden Picture Frame (Size, Colour, & Material Forms)
• A 1KG Strawberry Protein Supplement (Size & Flavour Forms)

The forms available for a Product are defined against the first variant in the feed using the forms field. Each comma-separated value in this field corresponds to a single form. Each variant must have a form-id_[Form-Name] and a form-value_[Form-Name] field for each form. form-swatch_[Form-Name] fields can be to enable a swatch picker. [Form-Name] should be substituted with one of the forms.

Example:

product-id,variant-id,forms,form-id_colour,form-value_colour,form-swatch_colour,form-id_size,form-value_size
001,sku_001,"colour,size",colour_white,White,https://cdn.shop.com/swatch/White.png,size_xx-small,XX-Small
001,sku_002,"colour,size",colour_white,White,https://cdn.shop.com/swatch/White.png,size_x-small,X-Small
001,sku_003,"colour,size",colour_white,White,https://cdn.shop.com/swatch/White.png,size_small,Small
001,sku_004,"colour,size",colour_white,White,https://cdn.shop.com/swatch/White.png,size_medium,Medium
001,sku_005,"colour,size",colour_white,White,https://cdn.shop.com/swatch/White.png,size_large,Large
001,sku_006,"colour,size",colour_white,White,https://cdn.shop.com/swatch/White.png,size_x-large,X-Large

In the App, the above feed snippet would appear as below. Each form will correspond to a picker that allows users to select a variant:

Images

Images can be provided to showcase Product Variants. Images are defined in the feed via the image_[index] field. [index] should be substituted with a zero-based numerical index. For example; image_0, image_1. Images are displayed and swipe-able in the app:

Links

Product Metadata Links can be used to link to external resources associated with the Product. Links are defined in the feed via the link-title_[index] and the link-url_[index]/link-content_[index] fields. [index] should be substituted with a zero-based numerical index. For example; link-title_0, link-url_0, link-content_0.

In cases where a given link is present for a large number of products, it is recommended to provide a URL to the content, instead of using the content field. The content field should be used sparingly for static content that is unique to the Product.

Example:

link-title_0,link-url_0,link-title_1,link-content_1
"Size Guide",https://cdn.shop.com/sizeguide.html,"Delivery Information","<p>Delivery Information Content<p>"

The screenshot below demonstrates how the above example would display Links in the Product Details Page:

Low On Stock

A Product Variant can be highlighted as being low on stock via the low-on-stock field in the feed. Variants that are low on stock have a message displayed against them:

Prices

Prices are defined in the feed via the price-now_[Poq-Currency-Identifier] and price-was_[Poq-Currency-Identifier] fields. [Poq-Currency-Identifier] should be substituted with a Poq Currency Identifier.

Product Variants may have multiple prices, this allows Apps that are available in different regions to use the same product data. The App should only display the price as available in the user's selected region and currency. By default, the first currency provided for the variant is used.

A variant's price is made up of a "Now Price" (The current price) and a "Was Price" (The price prior to reduction). When a Was Price is provided, the App will display reduction information:

Product Listings

The listing-id is a grouping ID which indicates that a group of product variants comprise a single product listing. Product listings are shown on pages such as the Wishlist or the Product Listing Page. For example, the blue & pink variants of a single T-shirt would appear as two items if their listing IDs were different, even if they were part of the same Product.

Users are able to add Product Listings to their Wishlists without selecting a specific Product Variant, for example, if Product Variants are grouped into Product Listings based on their colour, a user can add the green T-shirt to their Wishlist without having to select a specific size.

If no listing ID is defined, the product ID will be used instead. This means that the whole Product would appear as a listing.

Promotion Badges

Promotion badges appear on the Product Details Page to highlight a particular promotion:

Promotion Messages

Promotion messages do not appear in the Product Details Page by default, however they can be enabled via customisations on the App.

Release Date

The Release Date property is used by Poq's Search service when sorting Product Listings by the "New In" option. When a listing is made up of multiple variants, the first variant's release date is used.

Sort Index

The Sort Index property is used by Poq's Search service when sorting Product Listings by the "Featured" option. When a listing is made up of multiple variants, the first variant's sort index is used.

Videos

The video-url property can be used to provide a link to a video that showcases the Product Variant. Video URLs are defined at the Product Variant Level. If a Video URL is provided, an icon will be displayed in the Product Details Page that will open the video when tapped:

Glossary of Terms

Poq Currency Identifier

A unique identifier for a currency in a country. It consists of a required currency code and an optional country code.

Currency code is a 3-digit ISO 4217 code. Although it is expected to be a standard ISO code, it is not validated against the ISO standard. It must consist of upper case letters from the English alphabet.

Country code is a 2-digit ISO 3166 Alpha 2 code. Although it is expected to be a standard ISO code, it is not validated against the ISO Standard.

The format is as follows: (Required: [Currency Code])(Optional:_[Country Code])

Examples: GBP, EUR, EUR_DE, XBT_TW

Product

An abstract grouping of one or many Product Variants. For example, a shirt that comes in different sizes and different colours.

Product Variant

A distinct SKU of a given Product. For example, a medium green T-shirt.

Product Listing

An abstract grouping of many Product Variants for listing purposes. For more information, see Product Feed Deep Dive - Product Listings.

SKU

Initialism of 'Stock Keeping Unit'.

Now Price

The current price of a product variant.

Was Price

The previous price of a product variant.

Swatch Picker

An image based selection tool that allows users to select a form of a Product.