To support large product ranges common to the retail sector, Deliverect can receive an Item file for upload.
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
callbackUrlwhen the CSV file has been fully processed.
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."
]
}Item .csv Glossary
| 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;
Bundle Items
Translations
CSV Data - Glossary
Please note that all the fields marked with * are required.
Column Header | Description | Format |
|---|---|---|
| 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 |
| Certain aggregators might require a second category to be defined. | String |
| String | |
| Legal name of item | String |
| Unique identifier for a product | String |
| The cost of the item defined by an integer .
e.g. €5.50 euros is expressed without currency as | Float |
| Comma separated list of unique identifier (equivalent to EAN) | List of Strings |
| Percentage sales tax rate for item e.g. 21 corresponds to 21% | Integer |
| " | String |
| 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 number of products which can be selected on a deal. *Required when "dealsections" are provided. | Integer |
| Maximum number of products which can be selected on a deal. *Required when "dealsections" are provided. | Integer |
| 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 |
| Name used for internal reference | String |
| Product description | String |
| Food business operator name | String |
| Food business operator address | String |
| Food business operator brand name | String |
| Mandatory if "Weight Unit" column is filled in | Integer |
| Case sensitive - mandatory if "Weight" column is filled in |
|
| Mandatory if "Volume Unit" column is filled in | Integer |
| Case sensitive - mandatory if "Volume" column is filled in |
|
| Measure for product dimension |
|
| Float with 2 decimal digits e.g. 2.50 | Float |
| Float with 2 decimal digits e.g. 12.50 | Float |
| Float with 2 decimal digits e.g. 5.50 | Float |
| The measurement of the item as purchased e.g. A 500g pack of rice) → Sell Unit: g |
|
| The standard measurement of the item e.g. Cheese at $2.50 per 100 |
|
| "volume unit" , "weight unit" or "ea". "ea" refers to "each unit". |
|
| Float with 2 decimal digits | Float |
| Without decimals | Integer |
| Case sensitive |
|
| Includes allergens and other product tags, the list of accepted traits and their ENUM value here for accepted values | Enum List |
| Cloud hosted image URL separated by a comma (if multiple). See section here for more details | String |
| Accepted values : SNAP, HSA, FSA | List of Strings |
Product Traits
For the complete list of product traits (tags/allergens) to apply, you should reference the ENUM values listed in the page below;
Translations
The translatable elements for products are "name " & "description"
Section | Column Name |
|---|---|
name |
|
description |
|