Ingestion API

This guide lists steps to perform common operations using the Kwikee Ingestion API. 

On this page: 

  • The Red Text maps to exact header names in the “Kwikee Ingestion API Endpoint Reference Guide” document. 

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

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

COMMON ACTIONS

CREATE AND PUBLISH A NEW PRODUCT

  1. Use Ingestion API Dictionaries to find the appropriate brand ‘assetId’ for your new product 

  2. Use Create Product Version with product data structure 

    1. Use a ‘version’ value unique in and to your system 

  3. Use Kwikee Product Summary Query with the GTIN to retrieve the Product Version ‘assetId’ which was just created 

    1. The ‘versionString’ value in the returned structure matches the ‘version’ value used in the previous step 

  4. Create Image assets 

    1. Use Create/Update/Delete/Retrieve Product Image Asset with the image data as parameters 

      1. The image asset ‘assetId’ will be returned 

    2. Add all files to your product image ‘assetId’ 

      1. Use Create or Update Product Image Asset Files 

  5. Publish the product and image assets 

    1. Use Ingestion API Dictionaries to find the appropriate permission group ‘assetId’ 

    2. Use Adjust Permission Group with the “add” operation for the product version ‘assetId’ and each permission group ‘assetId’ 

    3. Use Adjust Permission Group with the “add” operation for each product image ‘assetId’ and each permission group ‘assetId’ 

PUBLISH A PRODUCT VERSION

  1. Use Kwikee Product Summary Query with the GTIN to retrieve the Product Version ‘assetId’ 

  2. Use Ingestion API Dictionaries to find the appropriate permission group ‘assetId’ 

  3. Use Adjust Permission Group with the “add” operation for the product version ‘assetId’ and each permission group ‘assetId’ 

UPDATE PRODUCT DATA

  1. Use Kwikee Product Summary Query with the GTIN to retrieve the Product Version ‘assetId’ 

  2. Use Retrieve Product Data to get the existing data structure 

  3. Update product data structure as needed 

  4. Use Update Product Version with product data structure 

UPDATE PRODUCT IMAGE DATA

  1. Use Kwikee Product Summary Query with the GTIN to retrieve the product image ‘assetId’ 

  2. Use Create/Update/Delete/Retrieve Product Image Asset to get the existing data structure 

  3. Update product image data as needed 

  4. Use Create/Update/Delete/Retrieve Product Image Asset with product image data as parameters 

PUBLISH A PRODUCT IMAGE

  1. Use Kwikee Product Summary Query with the GTIN to retrieve the Product Version ‘assetId’

  2. Use Ingestion API Dictionaries to find the appropriate permission group ‘assetId’

  3. Use Adjust Permission Group with the “add” operation for the product image ‘assetId’ and each permission group ‘assetId’

ADD A PRODUCT IMAGE

  1. Use Create/Update/Delete/Retrieve Product Image Asset with the image data as parameters 

    1. The image asset ‘assetId’ will be returned 

  2. Add the master file to your product image ‘assetId’ 

    1. Use Create or Update Product Image Asset Files 

    2. Standard Kwikee saves will be generated from the file uploaded, which is considered the “master” file. 

UPDATE A PRODUCT IMAGE FILE

  1. Use Create or Update Product Image Asset Files 

  2. Standard Kwikee saves will be generated from the file uploaded, which is considered the “master” file. 

PRODUCT IMAGE USAGE

This section provides a summary of Kwikee’s image asset attributes and how they are used. Given the great variety of product image types and specific use cases, please work with your Kwikee Project Coordinator to properly identify the images you are providing. 

Please reference the “Kwikee API Image Identification” document, which should accompany this document, for detailed information on how Kwikee identifies product images. 

STANDARD PRODUCT IMAGE SET

As defined in the “Kwikee API Image Identification”, the following information is presented as GS1 codes or Kwikee Special Purpose Codes. GS1 codes are a concatenated string in the following order, Image Type, Facing, Angle, and State.

Three Primary marketing images

  1. GS1 Codes: A1C1 - Front Marketing View

  2. GS1 Codes: A1L1 - Left Angled Marketing View

  3. GS1 Codes: A1R1- - Right Angled Marketing View

    One or more appropriate panel images, depending on the type of product

  1. GS1 Codes: L2 – Nutri-Fact Panel

  2. GS1 Codes: L4 – Ingredient Statement

  3. GS1 Codes: L5 – Ingredient Nutri-Fact Combo

  4. Kwikee special purpose code: SFK

  5. Kwikee special purpose code: DFK

SAMPLES 

The following visuals, shows the new GS1 codes with the Kwikee legacy view code.

Picture Picture

PRODUCTION WORKFLOW SUPPORT

Workflows within Kwikee are an ordered sequence of tasks, each of which is assigned to one or more teams. The production workflow support available in our API, provides the ability to assign a workflow to a list of assets, and the most common reason for using this feature is to request image processing on product images.  

Please work with your Kwikee Project Coordinator when you are deciding what workflows you need to use. 

CREATING IMAGES AND REQUESTING SHELFMAN FILE SAVES

The creation of shelfman file saves requires a set of product package image assets and the standard set includes all six sides of a product. These images are no plunge product facing images normally identified by GS1 codes: A1N1, A2N1, A3N1, A7N1, A8N1, A9N1.

  1. Follow one of the processes outlined above to create each of the product package image assets

  2. Record the image ‘assetId’s for the assets created that you need processed

  3. Call the Kwikee Production Work Flow Support endpoint with the following parameter values

  4. Name: “Digital Production: Shelfman”

  5. AssetIds: Comma separated list of your image ‘assetId’s

  6. These steps will create a group of image assets, for one or more products, and assign them the first task within the “Digital Production: Shelfman” workflow.

REQUESTING CLIP PATHS FOR A SET OF EXISTING PRODUCT IMAGES

  1. Use Kwikee Product Summary Query with the GTIN to retrieve the image assetsIds for images you want to have clip paths 

    1. You can make multiple calls, with different GTINs, to build one list of image ‘assetId’s for many products 

  2. Call the Kwikee Production Work Flow Support endpoint with the following parameter values 

    1. Name: “Digital Production: Clipping Paths” 

    2. AssetIds: Comma separated list of your image ‘assetId’s