Distribution API Usage Guide

This guide provides high-level steps to utilize the Kwikee Distribution API to maintain a channel specific database of product content. There are only five endpoints included in this guide and these endpoints can be used to access all content available to your distribution channel. Every entity distributed through the system is an asset with a unique ‘assetId’ including brands, product versions, product variants, and images. 

On this Page: 

  • Text in red font highlights the exact names of API endpoints like Product Summary by GTIN, each of which can be found at portal.kwikee.com in the appropriate API section for your use 

  • Attribute or parameter names are in single quotes like ‘assetId’ 

  • Values are in double quotes like “2000-01-01T00:00:00Z” 

ENDPOINT DESCRIPTIONS

The following descriptions summarize the five endpoints used on this page

  1. GTIN List Updated Since Date: Returns JSON with a paginated list of GTIN strings for current products on which data or images have changed since the provided timestamp.

  2. Product Summary by GTIN: Returns JSON with the product entity summary of the current version of the product with the provided GTIN. The summary includes all images, files and metadata, for that product entity. Also included are sub-structures with the ‘assetId’s of other related product entities like product versions and variants that are tied to the current product version.

  3. Product Summary by ID: Returns JSON with the product entity summary of the provided ‘assetId’ which can be the ‘assetId’ of any product version or product variant.

  4. Product Data by GTIN: Returns JSON with product data for the current version of the provided GTIN.

  5. Product Data by ID: Returns JSON with product data for the provided ‘assetId’ which can be a product version or product variant entity.

COMMON API USES

INITIALIZE OR REFRESH A DATABASE OF CONTENT

NOTES

  • This workflow focuses only on current product version assets and ignores other versions or variants.

STEPS

  1. Call the GTIN List updated since API endpoint with the following parameters

  2. Pass an empty value for the ‘updatedSince’ parameter

  3. You will need to make multiple calls with different ‘page’ values to receive the complete list of GTINs

  4. For each GTIN listed call the Product Summary by GTIN endpoint

  5. This data contains all of the image asset metadata and files that you may need to download

  6. Call the Product Data by GTIN endpoint with the GTIN from the previous step

  7. The returned data structure has all product data for the current product version

MAINTAIN ANOTHER DATABASE OF CONTENT THROUGH INCREMENTALS

NOTES 

  • This workflow focuses only on current product version assets and ignores other versions or variants 

  • The following steps are usually executed on a regular schedule, for example daily or weekly. However, the interval can be whatever you choose, as long you track the timestamp of the previous incremental execution. 

STEPS 

  1. Call the GTIN List Updated Since Date API endpoint with the following parameter 

    1. Parameter: ‘updatedSince’, value: “2019-06-25T00:00:00Z” 
      This value is the timestamp of your last initialization or incremental execution. 

  2. For each GTIN listed call the Product Summary by GTIN endpoint 

  3. In the returned data structure, compare the ‘lastModified’ date of the product record to your ‘updatedSince’ value 

    1. If the ‘lastModified’ date is newer, call the Product Data by GTIN endpoint with the ‘gtin’ from the previous step 

      1. The returned data structure has all the product data 

  4. For each image asset returned in the product data summary 

    1. Check if the image asset matches an image in your system and if it does 

      1. Compare the ‘lastModified’ date to your ‘updatedSince’ value 

      2. If the ‘lastModified’ date is newer download appropriate images files and metadata 

    2. If the image asset does not match one in your system, this may be a new image you need to download 

  5. For the next incremental, repeat steps 1 to 4 using an ‘updatedSince’ value of your previous incremental execution