Creating products and product variants using the add-basket endpoint
Contents
Overview
It is possible to use the basket_items array in the add-basket API endpoint to create a store of item metadata which can then be used to form segments used in Spaaza campaigns, populate item names on e-receipts and apps, and show performance using Spaaza’s analytics. For example, Spaaza can show statistics about how many items of category “Tops > Sweaters” are bought by a particular customer segment in physical stores in a month.
Spaaza’s object model contains the concept of products, product variants and barcodes. These three models have a hierarchical relationship. A product is an item sold in a transaction, for example “Aran Sweater,” which has various defined properties associated with it. A product can have multiple product variants, each one of which has its own properties. For example, one product variant of the product “Aran Sweater” might have a colour of “blue” and a size of “XL,” whilst another has colour “red” and size “M.” Each product variant can have one or more barcodes which is used to identify it in a transaction.
A product or product variant can be created by adding extra fields to the basket_items array in the call to the add-basket API endpoint. In order to create a product the retailer_product_code must be included in the basket_items array, and to create a product_variant the item_barcode must be included.
Once created, any basket items with new item_barcode values and an existing retailer_product_code will be associated with the product which has already been added.
Updates to product or product variant metadata can be passed by altering the fields sent in the basket_item JSON object. Updates will only be processed once in every six hour period - more frequent update attempts will be ignored. NOTE that this also means that any changes to item or product information, such as changes in name, will remain in place for at least 6 hours and may appear on receipts during this time.
Version-specific information
The following version-specific changes apply to this endpoint. See the versioning page for more details.
| Version | Change details |
|---|---|
| >= 1.4.11 | Use item_original_price value instead of item_price when creating products in BasketController->createProductFromAddBasket() method. |
Creating products via the add-basket endpoint
Product metadata fields
The fields which can be used to store item metadata are described below.
| Field | Description |
|---|---|
| retailer_product_code (string, mandatory) | The product or SKU identifier used by the retailer to identify the basket item. |
| item_barcode (string, mandatory) | The barcode used by the retailer to identify the item. |
| item_name (string) | The name of the product. |
| item_description (string) | The description of the product. |
| item_brand (string) | The brand making the product. |
| item_season (string) | The particular season that is associated with the product. |
| item_category (string) | A retailer category string for the product. This can be a single category name or can include a retailer category hierarchy with the names of category levels separated by the character “>”. For example this could be “Woollen Sweaters” or “Clothing > Tops > Sweaters > Woollen Sweaters”. The Spaaza product ingester interprets the hierarchical string and can run analytics on different category levels. |
| item_web_url (string) | The url link to the product page on the webshop. |
| item_image_url (string) | The url link to the products image. |
| item_original_price (float) | The original price, gross of any discounts, being charged for the single-quantity item. |
| item_cost_price (float) | The cost price of the product before any profit margin is added to make the SELL INCL sale price. This field can be used for simple margin analytics calculations on a per-item but also per-retailer or per-customer segment basis. |
| item_colour (string) | The colour of the product_variant eg. “red” or “green”. |
| item_size (string) | The size of the inventory item, e.g. “M” or “32”. |
Minimum required fields
The minimum information that is required to create a product is retailer_product_code and the item_original_price and the minimum required information to create a product_variant is the item_barcode.
When updating a product, the minimum required fields are retailer_product_code in order to identify the existing product, and any of the other parameters listed above.
Note: In the add-basket endpoints, additional fields are required - this section only describes the minimum required fields in order to create and update products. Please see the add-basket endpoint for more information on the required fields for the basket_items array.
Extract of basket_items array with minimum required information to create a product and a product_variant:
{
"basket_items":[
{
"item_barcode":"2913458432854",
"retailer_product_code":"iou342oi",
"item_original_price":125.00
}
]
}
Example request and response
An example request that will create a product and product_variant is shown below:
{
"entity":{
"entity_type":"chain",
"entity_id":1743
},
"user":{
"member_programme":"Spaaza",
"member_number":"303484"
},
"basket":{
"basket_platform_type":"in_store",
"retailer_basket_code":"20201019_test_00000001",
"basket_total_price":125,
"basket_timestamp_iso8601":"",
"basket_timezone_name":"Europe/Amsterdam",
"shipping_charge":0,
"payment_methods":[
],
"basket_currency":{
"currency_id":0,
"currency_code":"EUR"
},
"basket_tax":[
],
"basket_items":[
{
"item_barcode":"2913458432854",
"retailer_product_code":"iou342oi",
"item_name":"Men's Merino Aran Jumper",
"item_description":"The Aran Jumper is a style of jumper that takes its name from the Aran Islands off the west coast of Ireland.",
"item_price":125.00,
"item_original_price":125.00,
"item_subtotal": 125.00,
"item_colour":"White",
"item_gender":"M",
"item_brand":"Aran Jumpers ltd",
"item_size":"L",
"item_season":"Winter",
"item_category":"Clothing > Tops > Jumpers > Aran Jumper",
"item_image_url":"https://www.example.com/image.jpg"
}
]
}
}
This will result in the following response (edited to only include the relevant product information):
{
"result":{
"code":1,
"status":"ok"
},
"results":{
"basket":{
"id":1,
"chain_id":1,
"basket_platform_type":"in_store",
"currency_id":2,
"basket_total_price":125,
"retailer_basket_code":"20201019_test_00000001",
"basket_items":[
{
"product":{
"id":4,
"owner_code":"iou342oi",
"name":"Men's Merino Aran Jumper",
"description":"The Aran Jumper is a style of jumper that takes its name from the Aran Islands off the west coast of Ireland.",
"price":125,
"brand":"Aran Jumpers ltd",
"season":"Winter",
"category":"Clothing > Tops > Jumpers > Aran Jumper",
"webshop_url":null,
"image_url":"https://www.example.com/image.jpg",
"last_modified_date":"2020-10-19 08:31:18",
"created_date":"2020-10-19 08:31:18",
"product_variant":{
"id":2,
"condition":"new",
"colour":"White",
"barcode":[
],
"size":"M",
"price":125,
"cost_price":null,
"image_url":"https://www.example.com/image.jpg",
"web_url":null,
"last_modified_date":"2020-10-19 08:31:18",
"created_date":"2020-10-19 08:31:18"
}
},
"spaaza_product_variant_id":2,
"inventory_owner_code":null,
"item_barcode":"2913458432854",
"item_quantity":1,
"item_is_promotional":false,
"item_price":125,
"item_original_price":125,
"item_subtotal":125,
"is_identified":true,
"excluded_from_spaaza":false
}
],
"basket_vouchers_applied":[
],
"return_transactions":[
],
"payment_methods":[
],
"basket_tax":[
{
"id":1,
"basket_id":1,
"tax_rate":0.06,
"tax_total":100
}
],
"supplementary_basket_codes":null,
"regenerated_rewards":[
],
"honour_vouchers_applied":[
],
"employee":{
"employee_code":null,
"employee_name":null
},
"basket_timestamp_iso8601":"2020-10-19T08:31:18+00:00",
"basket_timezone_name":"UTC",
"purchase_progress":null
},
"user":{
"member_programme":"spaaza",
"member_number":3354863
},
"result_type":"add-basket"
}
}