Purpose

To process a complete update of all item data, a two step process is required to first request a signed URL via Google Cloud Services (GCS) and then to submit a CSV file with all item data via PUT request

Method

1.Request a Signed URL

Sending a request to this endpoint with a callbackUrl will return a signedUrl from GCS with specific headers.

2.Submit .csv file via PUT Request

Once a signedUrl is retrieved, the Item upload process is as follows;

Your Item .csv file should be submitted via a PUT request to the signedUrlwith all the headers provided
Deliverect will then process the CSV asynchronously and callback to the provided callbackUrl when the CSV file has been fully processed.

ⓘ Headers Required

Please ensure that all the headers returned from the signed URL are included within the PUT request

Example PUT Request

curl --location --request PUT 'https://storage.googleapis.com/cicd-signed-url/items.csv?x-goog-signature=13d3&x-goog-algorithm=GOOG4-RSA-SHA256&x-goog-credential=signed-url-poc%40test-demo-410111.iam.gserviceaccount.com%2F20240223%2Fasia-south1%2Fstorage%2Fgoog4_request&x-goog-date=20240223T080312Z&x-goog-expires=86400&x-goog-signedheaders=content-type%3Bhost%3Bx-goog-meta-callback%3Bx-goog-meta-user' \
--header 'Content-Type: text/csv' \
--header 'Host: storage.googleapis.com' \
--header 'x-goog-meta-callback: https://example.com/itemsCallback' \
--header 'x-goog-meta-user: your-user-id' \
--header 'x-goog-content-sha256: UNSIGNED-PAYLOAD' \
--data-binary '@items.csv'

Callback Response

{
    "file_id": "a420*******************************725b",
    "status": "success"
}

{
    "file_id": "d0f7*******************************d278",
    "status": "error",
    "errors":
    [
        "No products found in the file. Please check the file and try again."
    ]
}

Parameters

Parameter	Description
`callbackUrl`	An optional URL where we'll send a completion event when items CSV fully imported
`signedUrl`	Once the signed URL is created, it is valid for 15 minutes. This means that you have up to 15 minutes to initiate an upload via POST of the CSV to this endpoint. For more information please read: https://cloud.google.com/storage/docs/access-control/signed-urls
`fileId`	Included in the `callbackUrl` as a unique identifier to the item upload request

Item CSV Format

A single Item CSV is expected with below showing a complete example. This file can include the additional columns allowing Bundles and Translateable elements to be specified, which are shown in specific sample files below;

▶ Download Example CSV

Bundle Items

The CSV supports bundles (e.g. meal deals or combos), which have a fixed price and groups together products that normally have individual prices, but when included in the bundle are zero-priced.

Bundles need defined using two distinct values in the 'Product type' column as below;

Product Type	Description	Required Columns
deal	The bundle product defining the overall offer	A unique 'PLU ' A 'Base Price' (the fixed bundle price) Comma seperated list of each deal section PLU within 'Sub Items'
dealsection	A selection group within the bundle (e.g. "Choose your Starter")	A unique 'PLU ' Comma seperated list of each product PLU offered in the section within 'Sub Items' (products should already exist in the CSV)

Bundle Rules

Selection rules are defined for each dealsection using the Minimum and Maximum selection values

Column Name	Description
Minimum selection	Sets the minimum number of items a customer must choose
Maximum selection	Sets the maximum number of items a customer can choose

*See the example bundle '£15 Pizza + Wine Meal Deal' within the CSV example above

Translations

The translatable elements for products are "Name" & "Description" and should be added as seperate columns with an ISO-639-1 language code appended e.g. Name.fr / Description.fr language codes supported listed in the link below;

▶ Language Codes

CSV Data - Glossary

ⓘ Required Data

Please note that all the fields marked with * are required.

Column Header	Description	Format
`Category 1`*	Up to three levels of categorisation Category name must be unique across the whole Item file i.e. same exact name cannot be used in Category 1 and Category 2	String
`Category 2`*	Certain aggregators might require a second category to be defined.	String
`Category 3`		String
`Name`*	Legal name of item	String
`PLU`*	Unique identifier for a product	String
`Base Price`*	The cost of the item defined by an integer . e.g. €5.50 euros is expressed without currency as`5.50`	Float
`GTINs`*	Comma separated list of unique identifier (equivalent to EAN)	List of Strings
`Tax Rate`*	Percentage sales tax rate for item e.g. 21 corresponds to 21%	Integer
`Product type`	"`product`", "`deal`" or "`dealsection`" * Required to insert bundles/ meal deals	String
`Sub Items`	PLU of the subItems At "deal" level it represents the PLUs of the deal sections. At "dealsection" level it represents the item PLUs which should be a regular "product" type. * Required to insert bundles/ meal deals	String
`Minimum selection`	Minimum number of products which can be selected on a deal. *Required when "dealsections" are provided.	Integer
`Maximum selection`	Maximum number of products which can be selected on a deal. *Required when "dealsections" are provided.	Integer
`Maximum Quantity`	It defines how many times can the same subItem be chosen.A value of '2' for example, means that each item in a group can be selected at most 2 times.	Integer
`Description`	Product description	String
`Manufacturer Name`	Food business operator name	String
`Manufacturer Address`	Food business operator address	String
`Manufacturer Brand`	Food business operator brand name	String
`Weight`	Mandatory if "Weight Unit" column is filled in	Integer
`Weight Unit`	Case sensitive - mandatory if "Weight" column is filled in	`g`, `kg`, `mg`, `lb`, `oz`
`Volume`	Mandatory if "Volume Unit" column is filled in	Integer
`Volume Unit`	Case sensitive - mandatory if "Volume" column is filled in	`L`, `mL`, `gal`, `pt`, `oz`
`Dimension Unit`	Measure for product dimension	`m`, `cm`, `mm`, `in`, `ft`, `yd`
`Width`	Float with 2 decimal digits e.g. 2.50	Float
`Height`	Float with 2 decimal digits e.g. 12.50	Float
`Length`	Float with 2 decimal digits e.g. 5.50	Float
`Sell Unit`	The measurement of the item as purchased `un`or weight `g`, `kg`, `pd`, `oz` e.g. A 500g pack of rice) → Sell Unit: g	`un`, `g`, `kg`, `pd`, `oz`
`Price Unit`	The standard measurement of the item e.g. Cheese at $2.50 per 100 `g`	`un`, `g`, `kg`, `pd`, `oz`
`Net Quantity Unit`	"volume unit" , "weight unit" or "ea". "ea" refers to "each unit".	`L`, `mL`, `gal`, `pt`, `oz`, `g`, `kg`, `mg`, `lb`, `oz` or `ea`
`Net Quantity`	Float with 2 decimal digits	Float
`Energy`	Without decimals	Integer
`Energy Unit`	Case sensitive	`kJ`, `kcal`
`Product Traits`	Includes allergens and other product tags, the list of accepted traits and their ENUM value here	Enum List
`Image Links`	Cloud hosted image URL separated by a comma (if multiple). See section here for more details	String
`Program Eligibility`	Accepted values : SNAP, HSA, FSA	List of Strings