Ingest product information / v1

Overview

Ingest API provides a service to insert a new item to your Product Catalog. By utilizing the Ingest API, you can bypass the latency of the Clickstream Product Integration Method for product-related field inserts. As Catalog API provides endpoints to insert Product Catalog, you can send requests to insert your Product Catalogs directly.

Endpoint and Headers

POST https://catalog.api.useinsider.com/v1/ingest 

Headers

Body Parameters

The following product fields should be sent as parameters in the object with their field name and data type as stated. If any of the required fields is not sent through Catalog API, the respective product is not updated or inserted.

[{
        "item_id": "2159967",
        "category": [            
              "Home", "Garden Supplies", "Outdoor Furniture"
          ],
        "locale": "en_US",
        "image_url": "https://mywebsite.com/images/furniture.jpg",        
        "name": "Red Bean Bag",        
        "url": "https://mywebsite.com/read-bean-bag",        
        "in_stock": 0,     
        "price": {            
              "USD": 49.9        
          },        
        "discount": {            
              "USD": 9.9        
          },        
        "original_price": {            
              "USD": 49.9        
          },        
        "product_attributes": {           
              "brand_attribute":"bag brand",            
              "shipping_attribute":"Free Shipping",            
              "online_exclusive":"Online Exclusive",            
              "new_arrival_attribute":"New Arrival",            
              "id_product_attiribute":"2159967",            
              "stock_code":"2159967",            
              "item_code":"2159967"      
          }    
}]

Sample Responses

200 OK

Catalog API returns responses with status code 200 for successful requests. Successful responses display the number of valid products to be updated and the full information of the failed products.

{
	"success": true,
	"result": {
		"successful": {
			"count": 498
		},
		"fail": {
			"count": 2,
			"records": [
					{
					    "message": "'name' must be string.",
					    "data": {
                                     "item_id": "4295",
                                     "name": true,
                                     "url": "https://www.example.com/test-product.html",
                                     "locale": "tr_TR",
                                     "created_at": "2020-02-28 07:05:46",
                                     "product_attributes": {
                                         "store_id": "123",
                                         "color": "black",
                                         "brand_name": "nike"
                                     }
                                 },
					    "message": "Product attribute type doesn't match: 'store_id'",
					    "data": {
	                                 "item_id": "12345",
	                                 "name": "Siyah Spor Ayakkabı",
	                                 "url": "https://www.example.com/test-product.html",
	                                 "in_stock": 1,
	                                 "locale": "tr_TR",
	                                 "created_at": "2020-02-28 07:05:46",
	                                 "product_attributes": {
	                                     "store_id": false
	                                 }
	                             },
					}
			]
		}
	}
}

Ingest endpoint of the Catalog API can also be used to introduce products that need to be recorded within the same group. To this end, you should include the groupcode field in each product information. A sample request below introduces products in the same group to the Product Catalog.

[{
        "item_id": "2159967",
        "category": [            
              "Home", "Garden Supplies", "Outdoor Furniture"
          ],
        "locale": "en_US",
        "image_url": "https://mywebsite.com/images/furniture.jpg",        
        "name": "Red Bean Bag",        
        "url": "https://mywebsite.com/read-bean-bag",        
        "in_stock": 1,    
        "price": {            
              "USD": 40.9        
          },        
        "discount": {            
              "USD": 9.9        
          },        
        "original_price": {            
              "USD": 49.9        
          },
        "groupcode": "GRP-10000"         
},{
        "item_id": "2159968",
        "category": [            
              "Home", "Garden Supplies", "Outdoor Furniture"
          ],
        "locale": "en_US",
        "image_url": "https://mywebsite.com/images/furniture2.jpg",        
        "name": "Red Bean Bag 2",        
        "url": "https://mywebsite.com/read-bean-bag2",        
        "in_stock": 1,    
        "price": {            
              "USD": 11.3        
          },        
        "discount": {            
              "USD": 1.0        
          },        
        "original_price": {            
              "USD": 12.3        
          },
        "groupcode": "GRP-10000"         
}]

Ingest API can also return successful responses with warnings in the response body. These warnings refer to optional attributes that you entered wrongly. In such cases, products in the requests are still processed. However, product attributes causing the warnings are ignored and not updated in your Product Catalog. You can see below a sample request and a Catalog API response that contains a warning.

 [{
    "name": "Name of the Product",
    "item_id": "Item-123",
    "description": "A sample description",
    "in_stock": 1,
    "price": {
        "TRY": 35.5
    },
    "url": "https://my-website.com/my-sample-product",
    "image_url": "https://my-website.com/my-sample-product/image.png",
    "brand": "my-brand-bame",
    "locale": "en_US",
    "product_attributes": {
        "stock_code": "01020304"
    },
    "google_title": "Google title of my product",
    "discount": {
        "TRY": 0
    },
    "original_price": {
        "TRY": 35.5
    }
}]

In this example, if the stock_code attribute is not defined as a Product Attribute for you before requesting the Catalog API, responses include a warning message as below:

{
    "success": true,
    "results": {
        "successful": {
            "count": 1
        },
        "fail": {
            "count": 0,
            "records": []
        },
        "warnings": [{
            "data": "[{\"field\":\"stock_code\",\"message\":\"Product attribute keys are not included in partners attribute.(stock_code)is not included in partner attribute map.\"}]"
        }]
    }
}

400 Invalid Data Exception; Couldn't parse json

{
	"success": false,
	"message": "Request data is not in valid JSON format."
}

400 Maximum Allowed Record Count

{
	"success": false,
	"message": "Maximum allowed record count is exceeded."
}

400 Maximum Allowed Request Size

{
	"success": false,
	"message": "Maximum allowed request size is exceeded."
}

401 Partner cannot be validated

{
	"success": false,
	"message": "Partner does not have necessary integration settings for Catalog API."
}

401 Wrong Token Usage

{
	"success": false,
	"message": "Partner token authentication is unsuccessful."
}

429 Partner rate limit exceeded

{
	"success": false,
	"message": "Usage request rate of partner is exceeded for current period."
}

500 Internal Error

{
	"success": false,
	"message": "The request processing has failed because of an unknown error."
}

Limitations

• For all the limitations, refer here.