Products and catalogs
This article provides information on how you can integrate products and product catalogs data of your site with our platform.
Wait. Are you ready for this part?
So, we hope that you have some understanding of how to work with our APIs. If not, then we suggest that you go through the Introduction, generating, and using the API keys sections.
Our platform provides API endpoints that you can use to integrate products and product catalogs on your app or site with our platform. Integrating your products and catalogs in Blueshift helps you build intelligence around your product catalog using Blueshift’s powerful AI engine. You can build a personalized recommendation of products, compute product affinities for users, and use the product information in your campaigns. Here are the API endpoints that you can use to integrate products and catalog of your site/app with our platform:
However, before you get to the endpoints, we'd like you to review the attributes and use the recommended format to send data to us.
Attributes
When you make an API call, ensure that you pass the parameters in the format that we describe below:
| Attribute | Description | Example |
|---|---|---|
| product_id | Unique identifier of item. This is what you pass in the product_ids in your events, and the values that you pass should match exactly to the actual product_id. | "234jkhj2341kj3h241" |
| title | Title of the item. | "32" LCD TV" |
| web_link | URL of the item on your site. | "http://server/path.html" |
| image | A link to the image of the product on your site. | "http://server/path.html" |
| price | The selling price of the product. | 29 |
| category | An array of strings that defines the taxonomy of categories of your site. Start with the root. | "Home", "Home > Electronics" |
| brand | The brand name of the product on your site. | "Nike" |
| msrp | The maximum suggested retail price. | 35 |
| availability | The sku status. As in, if the product is in-stock or out-of-stock. | ["in stock","out of stock"] |
| start_date | The active/inactive status of a product. Use iso8601 format. | "2016-02-02T04:19:42Z" |
| end_date | The active/inactive status of a product. Use iso8601 format. | "2016-02-02T04:19:42Z" |
| parent_sku | The sku to tie all variants or child products together. | "123jhqjh1234123" |
| tags | An array of strings that denotes the group or collections of similar products. | ["televisions", "monitors"] |
| custom attribute (create your own). For example, alt_attrib_image | Another attribute that you want us to save. | ["Description of a product below its image"] |
You can use this endpoint to create a catalog on our platform that matches the catalog on your site. This endpoint takes a name for a catalog that you want to create. This endpoint returns the UUID of the catalog that it creates for you.
curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"catalog" : {"name" : "ACME Item Catalog"}}' -u <USER API KEY>: https://api.getblueshift.com/api/v1/catalogs
Here's how the sample response looks
{"catalog_uuid":"<CATALOG UUID>"}
You can use this endpoint to add products of a catalog on your app or site to the matching catalog that you create using the create a catalog endpoint. This endpoint takes the UUID (that you get from the create a catalog endpoint) and a list of products that you want to the catalog. You can add multiple items to a catalog in batches of 25 items at a time. We recommend you to limit the number of API calls to 5 per second.
curl -v -H "Accept: application/json" -H "Content-type: application/json" -X PUT -u <USER API KEY>: https://api.getblueshift.com/api/v1/catalogs/<CATALOG UUID>.json -d '
{
"catalog": {
"products": [
{
"brand": "Nike",
"category": [
"Home",
"Home > Shoes",
"Home > Shoes > Running"
],
"image": "http://server/path/image.jpg",
"msrp": "47",
"price": "37.99",
"product_id": "189909",
"availability": "in stock",
"tags": [
"running",
"athlete"
],
"title": "Nike Jordan Running Shoes in Blue",
"web_link": "http://server/path/product.html",
"latitude": "37.792805",
"longitude": "-122.401444",
"location_tag": "Points of Interest > USA > California > San Francisco > San Francisco Downtown"
},
{
"brand": "Reebok",
"category": [
"Home",
"Home > Shoes",
"Home > Shoes > Sports"
],
"image": "http://server/path/image2.jpg",
"msrp": "47",
"price": "37.99",
"product_id": "189910",
"availability": "in stock",
"tags": [
"basketball"
],
"title": "Reebok Basketball Shoes",
"web_link": "http://server/path/product2.html"
}
]
}
}'
This endpoint returns OK if the products are successfully added to the catalog. If there's an error in the list that you provide, here's the response that shows the error:
{
"products": [
{
"brand": "Nike",
"category": [
"Home",
"Home > Shoes",
"Home > Shoes > Running"
],
"image": "http://server/path/image.jpg",
"msrp": "47",
"price": "37.99",
"stock": "in stock",
"tags": [
"running",
"athlete"
],
"title": "Nike Jordan Running Shoes in Blue",
"web_link": "http://server/path/product.html",
"catalog_uuid": "326da192-e461-4151-bf16-0f7ef0ed6592",
"product_id": null
},
{
"brand": "Reebok",
"category": [
"Home",
"Home > Shoes",
"Home > Shoes > Sports"
],
"image": "http://server/path/image2.jpg",
"msrp": "47",
"price": "37.99",
"availability": "in_stock",
"tags": [
"basketball"
],
"web_link": "http://server/path/product2.html",
"catalog_uuid": "326da192-e461-4151-bf16-0f7ef0ed6592",
"product_id": "189910"
}
],
"errors": [
{
"product_id": [
"can't be blank"
]
},
{
"title": [
"can't be blank"
]
}
]
}
Updated 10 months ago