Authentication & Identification
In Tagalys, a Client can have multiple Stores. To make any sync / search request, both the client and store authentication and identification information should be present in the following format:
{
"identification":{
"client_code": "client-identification-code",
"api_key": "client-private-api-key",
"store_id": "store-identification-id"
}
}
Configuration
The following endpoint can be used to define stores, and inside each store: multiple currencies, sort options and custom fields. The products_count key can be approximate and is used for provisioning purposes. Even if your store has more products, all products will be processed.
POST: /v1/configuration
{
"stores": [
{
"id": "1",
"label": "English",
"currencies": [
{
"id": "HKD",
"label": "HK$",
"fractional_digits": 2,
"rounding_mode": "round",
"exchange_rate": 7.76,
"default": false
},
{
"id": "INR",
"label": "�",
"fractional_digits": 2,
"rounding_mode": "round",
"exchange_rate": 66.77,
"default": false
},
{
"id": "USD",
"label": "$",
"fractional_digits": 2,
"rounding_mode": "round",
"exchange_rate": 1.0,
"default": true
}
],
"fields": [
{
"name": "sale_price", // core fields like sku, price, sale_price etc. described in the next section don't have to be defined here, but they can be for the purpose of overriding labels or other options.
"type": "float",
"label": "Final Price",
"currency": true,
"filters": true,
"search": false
},
{
"name": "accessories_type",
"type": "string",
"label": "Accessories Type",
"currency": false,
"filters": false,
"search": true
},
{
"name": "genre",
"type": "string",
"label": "Genre",
"currency": false,
"filters": false,
"search": true
},
{
"name": "luggage_style",
"type": "string",
"label": "Luggage Style",
"currency": false,
"filters": false,
"search": true
}
],
"tag_sets": [
{
"id": "apparel_type",
"label": "Type",
"filters": true,
"search": true
},
{
"id": "color",
"label": "Color",
"filters": true,
"search": true
},
{
"id": "gender",
"label": "Gender",
"filters": true,
"search": true
},
{
"id": "size",
"label": "Size",
"filters": true,
"search": true
},
{
"id": "sleeve_length",
"label": "Sleeve Length",
"filters": true,
"search": true
},
{
"id": "__categories",
"label": "categories",
"filters": true,
"search": true
}
],
"sort_options": [
{
"field": "name",
"label": "Name"
},
{
"field": "price",
"label": "Price"
}
],
"locale": "en_US",
"multi_currency_mode": "exchange_rate",
"products_count": 21532
}
]
}
Product synchronization
The client's product catalogue should be synced with Tagalys on a continuous basis. Whenever relevant product attributes change, or when products are deleted, Tagalys should be notified.
Feed File Format
For any sync request, a file must be created with a jsonl extension. This is simply a file with one json per line.
{"perform":"index","payload":{"name":"Aviator Sunglasses","description":"Gunmetal frame with crystal gradient polycarbonate lenses in grey. ","short_description":"A timeless accessory staple, the unmistakable teardrop lenses of our Aviator sunglasses appeal to everyone from suits to rock stars to citizens of the world.","sku":"ace000","price":295,"accessories_type":"Eyewear","luggage_style":null,"__id":"337","link":"http:\/\/www.your-store.com\/index.php\/aviator-sunglasses.html","sale_price":295,"image_url":"http:\/\/www.your-store.com\/media\/catalog\/product\/a\/c\/ace000a_1.jpg","introduced_at":"2013-03-04T16:48:17-08:00","in_stock":true,"synced_at":"2016-11-02T09:40:01+00:00","__tags":[{"tag_set":{"id":"__categories","label":"categories"},"items":[{"id":"6","label":"Accessories","items":[{"id":"18","label":"Eyewear"}]}]},{"tag_set":{"id":"tax_class_id","label":"Tax Class"},"items":[{"label":"Taxable Goods","id":"2"}]},{"tag_set":{"id":"color","label":"Color"},"items":[{"label":"Silver","id":"15"}]},{"tag_set":{"id":"gender","label":"Gender"},"items":[{"label":"Male","id":"93"}]},{"tag_set":{"id":"material","label":"Material"},"items":[{"label":"Other","id":"130"}]}]}}
{"perform":"index","payload":{"name":"Jackie O Round Sunglasses","description":"Acetate frame. Polycarbonate lenses.","short_description":"These distinct, feminine frames balance a classic Jackie-O styling with a modern look. ","sku":"ace001","price":295,"accessories_type":"Eyewear","luggage_style":null,"__id":"338","link":"http:\/\/www.your-store.com\/index.php\/jackie-o-round-sunglasses.html","sale_price":225,"image_url":"http:\/\/www.your-store.com\/media\/catalog\/product\/a\/c\/ace001_1.jpg","introduced_at":"2013-03-04T16:48:17-08:00","in_stock":true,"synced_at":"2016-11-02T09:40:01+00:00","__tags":[{"tag_set":{"id":"__categories","label":"categories"},"items":[{"id":"6","label":"Accessories","items":[{"id":"18","label":"Eyewear"}]},{"id":"8","label":"Sale","items":[{"id":"28","label":"Accessories"}]}]},{"tag_set":{"id":"tax_class_id","label":"Tax Class"},"items":[{"label":"Taxable Goods","id":"2"}]},{"tag_set":{"id":"color","label":"Color"},"items":[{"label":"Red","id":"28"}]},{"tag_set":{"id":"gender","label":"Gender"},"items":[{"label":"Female","id":"94"}]},{"tag_set":{"id":"material","label":"Material"},"items":[{"label":"Other","id":"130"}]}]}}
{"perform":"index","payload":{"name":"Retro Chic Eyeglasses","description":"Acetate frame. Polycarbonate lenses.","short_description":"Madison Island Retro chic lenses are stylish on both men and women.","sku":"ace002","price":295,"accessories_type":"Eyewear","luggage_style":null,"__id":"339","link":"http:\/\/www.your-store.com\/index.php\/retro-chic-eyeglasses.html","sale_price":295,"image_url":"http:\/\/www.your-store.com\/media\/catalog\/product\/a\/c\/ace002a_1.jpg","introduced_at":"2013-03-04T16:48:17-08:00","in_stock":true,"synced_at":"2016-11-02T09:40:02+00:00","__tags":[{"tag_set":{"id":"__categories","label":"categories"},"items":[{"id":"6","label":"Accessories","items":[{"id":"18","label":"Eyewear"}]}]},{"tag_set":{"id":"tax_class_id","label":"Tax Class"},"items":[{"label":"Taxable Goods","id":"2"}]},{"tag_set":{"id":"color","label":"Color"},"items":[{"label":"Black","id":"20"}]},{"tag_set":{"id":"gender","label":"Gender"},"items":[{"label":"Male","id":"93"}]},{"tag_set":{"id":"material","label":"Material"},"items":[{"label":"Other","id":"130"}]}]}}
Each line of JSON represents action and details for a single product and should be in this format:
{
"perform": "index",
"payload": {
"__id": "337",
"name": "Aviator Sunglasses",
"description": "Gunmetal frame with crystal gradient polycarbonate lenses in grey. ",
"short_description": "A timeless accessory staple, the unmistakable teardrop lenses of our Aviator sunglasses appeal to everyone from suits to rock stars to citizens of the world.",
"sku": "ace000",
"price": 295,
"accessories_type": "Eyewear",
"luggage_style": null,
"link": "http://www.your-store.com/index.php/aviator-sunglasses.html",
"sale_price": 295,
"image_url": "http://www.your-store.com/media/catalog/product/a/c/ace000a_1.jpg",
"introduced_at": "2013-03-04T16:48:17-08:00",
"in_stock": true,
"synced_at": "2016-11-02T09:40:01+00:00",
"__tags": [
{
"tag_set": {
"id": "__categories",
"label": "categories"
},
"items": [
{
"id": "6",
"label": "Accessories",
"items": [ // items can be nested
{
"id": "18",
"label": "Eyewear"
}
]
}
]
},
{
"tag_set": {
"id": "color",
"label": "Color"
},
"items": [
{
"label": "Silver",
"id": "15"
},
{ // multiple items can be included
"label": "Gray",
"id": "18"
}
]
},
{
"tag_set": {
"id": "gender",
"label": "Gender"
},
"items": [
{
"label": "Male",
"id": "93"
}
]
}
]
}
}
Notes:
- perform should be index (create / update (complete product details should be present for updates)) or delete
- payload should contain the details of the product
- __id should be a unique identifier for this product. This is the field that will be used if any references to this product has to be saved.
- The following fields should be present:
- name
- sku
- link
- image_url
- price
- sale_price
- in_stock
- introduced_at
- synced_at
- Tags assigned to the product should be specified inside __tags which should be an array with the following keys:
- tag_set which should include the id and label of the category of the tag
- items should should include the id and label of the tag itself. Items can be nested using the item key.
Full feed sync
To begin with, dump your entire set of products into a file and call the following endpoint:
POST: /v1/products/sync_feed
{
"identification": { ... },
"link": "http://www.your-store.com/path/to/feed-file.jsonl?authkey=hdt24628dhw8dg2d6",
"updates_count": 21532,
"callback_url": "http://www.yours-store.com/feed-callback"
}
http://www.your-store.com/path/to/feed-file.jsonl?authkey=hdt24628dhw8dg2d6
---
{"perform":"index","payload":{"name":"Aviator Sunglasses","description":"Gunmetal frame with crystal gradient polycarbonate lenses in grey. ","short_description":"A timeless accessory staple, the unmistakable teardrop lenses of our Aviator sunglasses appeal to everyone from suits to rock stars to citizens of the world.","sku":"ace000","price":295,"accessories_type":"Eyewear","luggage_style":null,"__id":"337","link":"http:\/\/www.your-store.com\/index.php\/aviator-sunglasses.html","sale_price":295,"image_url":"http:\/\/www.your-store.com\/media\/catalog\/product\/a\/c\/ace000a_1.jpg","introduced_at":"2013-03-04T16:48:17-08:00","in_stock":true,"synced_at":"2016-11-02T09:40:01+00:00","__tags":[{"tag_set":{"id":"__categories","label":"categories"},"items":[{"id":"6","label":"Accessories","items":[{"id":"18","label":"Eyewear"}]}]},{"tag_set":{"id":"tax_class_id","label":"Tax Class"},"items":[{"label":"Taxable Goods","id":"2"}]},{"tag_set":{"id":"color","label":"Color"},"items":[{"label":"Silver","id":"15"}]},{"tag_set":{"id":"gender","label":"Gender"},"items":[{"label":"Male","id":"93"}]},{"tag_set":{"id":"material","label":"Material"},"items":[{"label":"Other","id":"130"}]}]}}
{"perform":"index","payload":{"name":"Jackie O Round Sunglasses","description":"Acetate frame. Polycarbonate lenses.","short_description":"These distinct, feminine frames balance a classic Jackie-O styling with a modern look. ","sku":"ace001","price":295,"accessories_type":"Eyewear","luggage_style":null,"__id":"338","link":"http:\/\/www.your-store.com\/index.php\/jackie-o-round-sunglasses.html","sale_price":225,"image_url":"http:\/\/www.your-store.com\/media\/catalog\/product\/a\/c\/ace001_1.jpg","introduced_at":"2013-03-04T16:48:17-08:00","in_stock":true,"synced_at":"2016-11-02T09:40:01+00:00","__tags":[{"tag_set":{"id":"__categories","label":"categories"},"items":[{"id":"6","label":"Accessories","items":[{"id":"18","label":"Eyewear"}]},{"id":"8","label":"Sale","items":[{"id":"28","label":"Accessories"}]}]},{"tag_set":{"id":"tax_class_id","label":"Tax Class"},"items":[{"label":"Taxable Goods","id":"2"}]},{"tag_set":{"id":"color","label":"Color"},"items":[{"label":"Red","id":"28"}]},{"tag_set":{"id":"gender","label":"Gender"},"items":[{"label":"Female","id":"94"}]},{"tag_set":{"id":"material","label":"Material"},"items":[{"label":"Other","id":"130"}]}]}}
{"perform":"index","payload":{"name":"Retro Chic Eyeglasses","description":"Acetate frame. Polycarbonate lenses.","short_description":"Madison Island Retro chic lenses are stylish on both men and women.","sku":"ace002","price":295,"accessories_type":"Eyewear","luggage_style":null,"__id":"339","link":"http:\/\/www.your-store.com\/index.php\/retro-chic-eyeglasses.html","sale_price":295,"image_url":"http:\/\/www.your-store.com\/media\/catalog\/product\/a\/c\/ace002a_1.jpg","introduced_at":"2013-03-04T16:48:17-08:00","in_stock":true,"synced_at":"2016-11-02T09:40:02+00:00","__tags":[{"tag_set":{"id":"__categories","label":"categories"},"items":[{"id":"6","label":"Accessories","items":[{"id":"18","label":"Eyewear"}]}]},{"tag_set":{"id":"tax_class_id","label":"Tax Class"},"items":[{"label":"Taxable Goods","id":"2"}]},{"tag_set":{"id":"color","label":"Color"},"items":[{"label":"Black","id":"20"}]},{"tag_set":{"id":"gender","label":"Gender"},"items":[{"label":"Male","id":"93"}]},{"tag_set":{"id":"material","label":"Material"},"items":[{"label":"Other","id":"130"}]}]}}
---
You can use callback_url to point to a route in your application that performs actions like deleting the feed file. The callback URL will be called via the POST method with the following details:
{
"identification": { ... },
"completed": "http://www.your-store.com/path/to/feed-file.jsonl?authkey=hdt24628dhw8dg2d6"
}
Updates / Deletes
As products are added/updated/deleted, save the updates into a jsonl file and call the following endpoint:
POST: /v1/products/sync_updates
{
"identification": { ... },
"link": "http://www.your-store.com/path/to/updates-file.jsonl?authkey=hdt24628dhw8dg2d6",
"updates_count": 7,
"callback_url": "http://www.yours-store.com/update-callback"
}
http://www.your-store.com/path/to/updates-file.jsonl?authkey=hdt24628dhw8dg2d6
---
{"perform":"index","payload":{"name":"Aviator Sunglasses","description":"Gunmetal frame with crystal gradient polycarbonate lenses in grey. ","short_description":"A timeless accessory staple, the unmistakable teardrop lenses of our Aviator sunglasses appeal to everyone from suits to rock stars to citizens of the world.","sku":"ace000","price":295,"accessories_type":"Eyewear","luggage_style":null,"__id":"337","link":"http:\/\/www.your-store.com\/index.php\/aviator-sunglasses.html","sale_price":295,"image_url":"http:\/\/www.your-store.com\/media\/catalog\/product\/a\/c\/ace000a_1.jpg","introduced_at":"2013-03-04T16:48:17-08:00","in_stock":true,"synced_at":"2016-11-02T09:40:01+00:00","__tags":[{"tag_set":{"id":"__categories","label":"categories"},"items":[{"id":"6","label":"Accessories","items":[{"id":"18","label":"Eyewear"}]}]},{"tag_set":{"id":"tax_class_id","label":"Tax Class"},"items":[{"label":"Taxable Goods","id":"2"}]},{"tag_set":{"id":"color","label":"Color"},"items":[{"label":"Silver","id":"15"}]},{"tag_set":{"id":"gender","label":"Gender"},"items":[{"label":"Male","id":"93"}]},{"tag_set":{"id":"material","label":"Material"},"items":[{"label":"Other","id":"130"}]}]}}
{"perform":"delete","payload":{"__id":"338"}}
---
