Skip to content

Export using templates

The Export product groups endpoint allows Voyado Elevate to function somewhat as a data repository from which transformable product data can be extracted.

When using the endpoint with a HTTP POST-method, a template to transform the output data can be added to its request body. A template, used together with a productRules query parameter, allows for an optimized and highly customized export that can be used as a base for imports into other e-commerce systems.

Templates are only for use with the HTTP POST-method

The endpoint should not be queried using the HTTP POST-method if no template is present in the body. Not providing a template will return a result where the JSON representation has the content type text/plain.

To return a result with the content type application/json, query the endpoint using the HTTP GET-method.

Max execution time of the HTTP POST-method

The max execution time is 29 seconds, if this limit is reached a 504 Gateway Timeout response will be generated. This will mean it will not be suitable for large catalogues. For those, use the GET method instead, and process the JSON response.

Writing templates

Templates to use with the Product groups export endpoint are written using the Handlebars syntax. Using the Handlebars syntax, the exported data in JSON can be considered as an object with properties that can be iterable and selected.

For more information about the templating language syntax, see the Handlebars documentation

Example

The following example uses a template to export product data into the delimited .csv-format. The template will have the headers market, productgroupkey, productkey, and variantkey. The product groups, products, and variants will be iterated, and the values for market and the respective keys for each level will be returned.

Template

market;productgroupkey;productkey;variantkey
{{#productGroups}}
{{#each products}}
    {{#each variants}}
    {{~../../../market}};{{../../key}};{{../key}};{{key}}
    {{/each}}
{{/each}}
{{/productGroups}}

Product data

JSON 
{
  "market": "UK"
  "locale": "en-GB"
  "productGroups": [
    {
      "key": "1001"
      "brand": "Gazelle"
      "department": "Men"
      "suppressDuplicates": false
      "products": [
        {
          "key": "1001-100"
          "title": "Linen T-shirt"
          "url": "/products/1001-100"
          "description": "Loose-fit striped T-shirt with a slightly lower neckline."
          "releaseDate": "2019-10-27T00:00:00Z"
          "images": [
            {
              "tags": []
              "customAttributes": []
              "urls": [
                {
                  "url": "//cdn.example.com/images/1001-100_model.jpg?preset=200x200"
                }
                {
                  "url": "//cdn.example.com/images/1001-100_model.jpg?preset=600x600"
                }
              ]
            }
            {
              "tags": []
              "customAttributes": []
              "urls": [
                {
                  "url": "//cdn.example.com/images/1001-100_cutout.jpg?preset=200x200"
                }
                {
                  "url": "//cdn.example.com/images/1001-100_cutout.jpg?preset=600x600"
                }
              ]
            }
          ]
          "customAttributes": {
            "category": [
              {
                "T-Shirts": "T-Shirts"
              }
            ]
            "season": [
              {
                "Summer": "Summer"
              }
            ]
            "style": [
              {
                "Casual": "Casual"
              }
            ]
          }
          "variants": [
            {
              "key": "1001-100-1"
              "cost": 8.0
              "listPrice": 12.99
              "sellingPrice": 9.99
              "sizes": [
                {
                  "size": "S"
                }
              ]
              "stockNumber": 12
              "url": "/products/1001-100?size=S"
              "stores": []
              "customPrices": []
            }
            {
              "key": "1001-100-2"
              "cost": 8.0
              "listPrice": 12.99
              "sellingPrice": 9.99
              "sizes": [
                {
                  "size": "M"
                }
              ]
              "stockNumber": 0
              "url": "/products/1001-100?size=M"
              "stores": []
              "customPrices": []
            }
            {
              "key": "1001-100-3"
              "cost": 8.0
              "listPrice": 12.99
              "sellingPrice": 9.99
              "sizes": [
                {
                  "size": "L"
                }
              ]
              "stockNumber": 5
              "url": "/products/1001-100?size=L"
              "stores": []
              "customPrices": []
            }
          ]
        }
      ]
    }
  ]
}

Output

market;productgroupkey;productkey;variantkey
UK;1001;1001-100;1001-100-1
UK;1001;1001-100;1001-100-2
UK;1001;1001-100;1001-100-3

Template helper functions

The templating engine allows for helpers to extend the standard functionality. Helpers are methods which expand Handlebars with operations that are not included in its standard set of functions.

For more information about additional helper functions and advanced data transformations, please contact Voyado Support.

Json .

The Json . (Json dot) function helps the template designer to print the contents of the current JSON object. By default, the double curly bracket, {{ }}, Handlebar syntax returns an HTML encoded string. If the contents of the current JSON object is to be printed, the raw output syntax of triple curly brackets, {{{ }}}, should be used with the Json dot function.

Example

The following example prints the contents of the current JSON object.

market;productgroupkey;productkey;variantkey
{{#productGroups}}
{{#each products}}
  {{#each variants}}
  {{{json .}}}
  {{/each}}
{{/each}} 
{{/productGroups}}

Product data

JSON 
{
  "market": "UK"
  "locale": "en-GB"
  "productGroups": [
    {
      "key": "1001"
      "brand": "Gazelle"
      "department": "Men"
      "suppressDuplicates": false
      "products": [
        {
          "key": "1001-100"
          "title": "Linen T-shirt"
          "url": "/products/1001-100"
          "description": "Loose-fit striped T-shirt with a slightly lower neckline."
          "releaseDate": "2019-10-27T00:00:00Z"
          "images": [
            {
              "tags": []
              "customAttributes": []
              "urls": [
                {
                  "url": "//cdn.example.com/images/1001-100_model.jpg?preset=200x200"
                }
                {
                  "url": "//cdn.example.com/images/1001-100_model.jpg?preset=600x600"
                }
              ]
            }
            {
              "tags": []
              "customAttributes": []
              "urls": [
                {
                  "url": "//cdn.example.com/images/1001-100_cutout.jpg?preset=200x200"
                }
                {
                  "url": "//cdn.example.com/images/1001-100_cutout.jpg?preset=600x600"
                }
              ]
            }
          ]
          "customAttributes": {
            "category": [
              {
                "T-Shirts": "T-Shirts"
              }
            ]
            "season": [
              {
                "Summer": "Summer"
              }
            ]
            "style": [
              {
                "Casual": "Casual"
              }
            ]
          }
          "variants": [
            {
              "key": "1001-100-1"
              "cost": 8.0
              "listPrice": 12.99
              "sellingPrice": 9.99
              "sizes": [
                {
                  "size": "S"
                }
              ]
              "stockNumber": 12
              "url": "/products/1001-100?size=S"
              "stores": []
              "customPrices": []
            }
            {
              "key": "1001-100-2"
              "cost": 8.0
              "listPrice": 12.99
              "sellingPrice": 9.99
              "sizes": [
                {
                  "size": "M"
                }
              ]
              "stockNumber": 0
              "url": "/products/1001-100?size=M"
              "stores": []
              "customPrices": []
            }
            {
              "key": "1001-100-3"
              "cost": 8.0
              "listPrice": 12.99
              "sellingPrice": 9.99
              "sizes": [
                {
                  "size": "L"
                }
              ]
              "stockNumber": 5
              "url": "/products/1001-100?size=L"
              "stores": []
              "customPrices": []
            }
          ]
        }
      ]
    }
  ]
}

Output

market;productgroupkey;productkey;variantkey
{"key":"1001-100-1","cost":8,"listPrice":12.99,"sellingPrice":9.99,"sizes":[{"size":"S"}],"stockNumber":12,"url":"/products/1001-100?size=S","stores":[],"customPrices":[]}
{"key":"1001-100-2","cost":8,"listPrice":12.99,"sellingPrice":9.99,"sizes":[{"size":"M"}],"stockNumber":0,"url":"/products/1001-100?size=M","stores":[],"customPrices":[]}
{"key":"1001-100-3","cost":8,"listPrice":12.99,"sellingPrice":9.99,"sizes":[{"size":"L"}],"stockNumber":5,"url":"/products/1001-100?size=L","stores":[],"customPrices":[]}

Template examples

This section includes template examples for some of the most popular import and export formats. As each template is targeted towards different platforms, it is important for integrators to have a good knowledge of the constraints and rules of the format they intend to use.

Data feed design considerations

For optimal template usage, the Data feed should include all required and important attributes of the target format. It is recommended to validate the attributes and their values before importing them into Elevate.

All templates have been tested by Voyad using the Advanced file syntax example of the Data feed format specification.

Google Shopping (Merchant) feed template

The Google Merchant product feed is recognized by several platforms. Google also provide feeds for Merchant product updates, boosting, inventory, ratings, and more. As these feeds are structured in a similar manner, the template example will only cover the contents of the product feed.

An example of a usable attribute to include as a custom attribute is [google_product_category] as Elevate does not track product categories from Google. If a product belongs to a specific Google category, such as Apparel, attributes for gender, age groups, and other apparel related attributes are recommended to include as custom attributes. Google also offers the ability to create both custom labels and attributes for their feed in the Google Merchant Center. If such labels and attributes are to be used, they must also be present in the Elevate data feed.

A variant must have an [item_group_id] attribute referencing its parent product as the Google item group ID is not necessarily the key of an Elevate product group.

Third party e-commerce platforms

Third party e-commerce platforms such as Shopify, Bigcommerce, Magento, and Shopware can use a Google Merchant product feed, but they are not necessarily as restrictive as the Google Merchant Center. This means that some of the required attributes of the Google Merchant Center can be omitted in imports to them. For more information, see the documentation for respective platform.

Download the Google Shopping feed template example

Custom JSON feed template

Product feeds in the JSON format are supported by several e-commerce platforms. Even though the Export product groups endpoint produces a result in the JSON format, some post-processing of the export may be needed before it can be imported into third party e-commerce platforms such as Magento, Salesforce, and Sniffie.

The Custom JSON feed template example is an example of an SKU based JSON, inspired by several e-commerce platforms with multilingual support. The template shows the benefit of using the Json . (dot) template helper to select JSON data from Elevate and embedding in a new format.

Download the Custom JSON feed template example

CSV template

Comma Separated Values, .csv, files (or Tab Separated Values, .tsv-files) are supported by many e-commerce platforms. The CSV template example is a mixture of several different .csv-formats and naming conventions inspired by Shopify, Bigcommerce, WooCommerce, and others.

Download the CSV template example

Best practices

  • Always use the limit or productRules parameters when developing templates. This will improve development time and debugging. Omitting these parameters will result in a drain of Elevate cluster resources.
  • Always use a sandbox/development environment when developing templates in order to not affect the production environment.
  • Avoid recursive calls.
  • Only use well tested templates in a production environment.
×
Copyright

This online publication is intellectual property of Voyado Lund AB. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Voyado Lund AB nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Voyado Lund AB essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE