Ingest product information

The Ingest API allows you to insert new items into your product catalog. As part of the Catalog API, it provides endpoints for ingesting product catalogs, enabling you to send direct requests to add product data into the catalog.

Endpoint and Headers

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

Visit our Postman collection to test this request.

Headers

Headers	Sample Value	Description
X-PARTNER-NAME	my-parter-name	This is your partner name. Navigate to InOne > Inone Settings > Account Settings to copy your partner name. The partner name should be lowercase.
X-REQUEST-TOKEN	1a2b3c4d5e6f	This key is required to authorize your request. Refer to API Authentication Tokens to generate your Catalog API token.

Query Parameters

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

If any undefined attribute is sent through the Catalog API, the respective product(s) will be updated without the undefined attribute(s). Refer to the Product Catalog Attribute List for details.

Field Name	Description	Data Type	Required
item_id	Unique product ID	String	Yes
locale	Language of the website	String	Yes
name	Name of the product	String	Yes
url	URL address of the product	String	Yes
image_url	URL address of the product image	String	Yes
category	Category tree of the product	Array (of string)	Yes
description	Product description	String	No
price	Unit price of the product. Object key is currency (string) and the value will be in float type.	Object {String:Float}	Yes
original_price	Original price of the product without any discount. Object key is currency (string) and the value will be in float type.	Object {String:Float}	Yes
in_stock	Stock status of the product	Integer	Yes
variants	Other variants of the given product ID	Array (of string)	No
brand	Brand information of the product	String	No
color	Color information of the product	String	No
size	Size information of the product	String	No
groupcode	Information for group product variants.	String	No
product_attributes	Object of the custom product attributes	Object {key:value}	No

The discount rate is automatically calculated based on the price and original price values you provided in the payload.

Sample Request 1

The sample below displays a request to insert a new product into your catalog using the Ingest API.

Products are sent in JSON format and can be batched inside a comma-separated list for efficiency.

[{
        "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 Response 1

Catalog API returns responses with a status code 200 for successful requests.

{
    "success": true,
    "message": {
        "invalidRatio": 0,
        "valid": {
            "count": 1
        },
        "invalid": {
            "count": 0,
            "details": []
        },
        "warnings": {
            "count": 1,
            "details": [
                {
                    "message": "Product attribute keys are not included in partners attribute.(brand_attribute)is not included in partner attribute map.",
                    "count": 1,
                    "document_ids": [
                        "2159967:en_US"
                    ]
                },
                {
                    "message": "Product attribute keys are not included in partners attribute.(id_product_attiribute)is not included in partner attribute map.",
                    "count": 1,
                    "document_ids": [
                        "2159967:en_US"
                    ]
                },
                {
                    "message": "Product attribute keys are not included in partners attribute.(item_code)is not included in partner attribute map.",
                    "count": 1,
                    "document_ids": [
                        "2159967:en_US"
                    ]
                },
                {
                    "message": "Product attribute keys are not included in partners attribute.(new_arrival_attribute)is not included in partner attribute map.",
                    "count": 1,
                    "document_ids": [
                        "2159967:en_US"
                    ]
                }
            ]
        }
    }
}

Successful responses display the number of valid products to be inserted and the complete information about the failed products.

Sample Request 2

The sample below displays a request to insert multiple products into the same group within your product catalog.

When you need to record related products together, the groupcode field should be included in each product’s information. All products with the same groupcode will be associated as a group in the 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"         
}]

Sample Response 2

Ingest API can also return successful responses with warnings in the response body. These warnings refer to optional attributes being entered by the user incorrectly. In such cases, products in the requests are still processed. However, product attributes causing the warnings are ignored and not inserted into your product catalog. Below, a sample request and a Catalog API response that contains a warning are shown.

 [{
    "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 the example below, if the stock_code attribute is not defined as a Product Attribute before requesting the Catalog API, responses include a warning message as follows:

{
    "success": true,
    "message": {
        "invalidRatio": 0,
        "valid": {
            "count": 1
        },
        "invalid": {
            "count": 0,
            "details": []
        },
        "warnings": {
            "count": 1,
            "details": [
                {
                    "message": "Product attribute keys are not included in partners attribute.(stock_code)is not included in partner attribute map.",
                    "count": 1,
                    "document_ids": [
                        "Item-123:en_US"
                    ]
                }
            ]
        }
    }
}

400 Invalid Data Exception; Couldn’t Parse JSON

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

400 Maximum Allowed Record Count

This response indicates that the maximum allowed record count is exceeded, which is 10000.

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

400 Maximum Allowed Request Size

This response indicates that the maximum allowed request size is exceeded, which is 5 MB.

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

401 Partner Cannot Be Validated

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

401 Wrong Token Usage

This response indicates that the provided API key is invalid, expired, or revoked. Refer to API Authentication Tokens to get or renew your API key.

{
	"status": false,
	"message": "Partner token authentication failed."
}

500 Internal Server Error

{
	"status": false,
	"message": "Internal server error."
}

Limitations

For all the limitations, refer to Catalog API Limitations.

Ingest Product Information