Products API

The Products API is essential for populating and updating the product catalog, ensuring accurate and up-to-date product information in Discovery OS.

This API allows for the creation of new product entries or updates to existing products within the catalog. Each product is identified by a unique reference ID (refId), and the API supports bulk updates.

IMPORTANT:

Atleast one product is required per API call.
A maximum of 1000 products are allowed per API call.
All fields and attributes must be supplied. Any missing fields will be set to null or empty.

API Endpoint

Method: POST

URL: https://<PA_END_POINT>/3.0/products

Request Header

Name	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer ACCESS_TOKEN`

Request Parameters (Body)

products (array) [REQUIRED]

Parameter	Type	Required	Description
`refId`	`string`	✅	A unique identifier for the product. Maximum length 255 character.
`itemGroupId`	`string`	✅	A unique identifier for the group of products. This can be used to group similar products together. If no grouping is available/required, set it same as the refId.
`name`	`string`	✅	The product name. Maximum length 255 character.
`description`	`string`	❌	A detailed description of the product.
`sku`	`string`	❌	Stock Keeping Unit, a unique identifier for each product variant. Maximum length 128 character.
`url`	`string`	✅	The URL to the product page. Provide valid URL with http or https.
`isInStock`	`boolean`	✅	Indicates whether the product is currently in stock.
`brand`	`object`	❌	The brand information containing- - `name (string)`: The name of the brand. - `logoUrl (string)`: The logo image URL.
`images`	`array of strings`	❌	Provide valid URL with http or https.
`prices`	`array of object`	❌	Contains price details - - `code (string)`: The currency code. - `price (number)`: The price of the product. - `discountPrice (number)`: The discounted sale price (if applicable).
`contents`	`array of object`	❌	Contains language-specific contents if the content needs to be displayed in multiple languages - - `langaugeTag (string)`: The language tag. Follow the standardised IETF language tags. - `name (string)`: The product name for the specific language tag. - `description (string)`: The product description for the specific language tag. - `url (string)`: The product URL for the specific language tag. It can be the same as the base URL if a separate URL is not used for the specific language.
`attributes`	`array of object`	❌	The attributes of the product. Each attribute will contain the following properties - - `name (string)` `REQUIRED`: Name of the attribute. - `stringValue (string)`: The string value of the attribute if it is a string. - `scalarValue (number)`: The numerical value of the attribute if it is a number. - `options (array of objects)`: The value options of the attribute. Each value will contain the following properties - -`value (string)`: The option value.

Example Request Payload

{
    "products": [
        {
            "refId": "ABC123",
            "name": "UltraBoost Running Shoes",
            "description": "High-performance running shoes with responsive cushioning.",
            "sku": "SKU-UBR123",
            "url": "http://www.company.com/product/ultraboost",
            "isInStock": true,
            "itemGroupId": "MEN-SPORTS",
            "brand": {
                "name": "Adidas",
                "logoUrl": "http://www.company.com/brand/adidas.jpg"
            },
            "images": [
                "https://www.company.com/images/ultraboost1.jpg",
                "https://www.company.com/images/ultraboost2.jpg"
            ],
            "prices": [
                {
                    "price": 180.00,
                    "code": "USD",
                    "discountPrice": 150.00
                },
                {
                    "price": 240.00,
                    "code": "AUD"
                }
            ],
            "contents": [
                {
                    "languageTag": "en-AU",
                    "name": "UltraBoost Running Shoes",
                    "description": "Experience unmatched performance with the UltraBoost series.",
                    "url": "http://www.company.com/au/product/ultraboost"
                },
                {
                    "languageTag": "ja-JP",
                    "name": "UltraBoost Running Shoes",
                    "description": "High-performance running shoes designed for maximum comfort.",
                    "url": "http://www.company.com/jp/product/ultraboost"
                }
            ],
            "attributes": [
                {
                    "name": "Material",
                    "stringValue": "Synthetic Mesh"
                },
                {
                    "name": "Weight",
                    "scalarValue": 250
                },
                {
                    "name": "Categories",
                    "options": [
                        {"value": "Clothing"},
                        {"value": "Footwear"},
                        {"value": "Sports"}
                    ]
                },
                {
                    "name": "Color",
                    "options": [
                        {"value": "Black"},
                        {"value": "White"}
                    ]
                }
            ]
        },
        {
            "refId": "XYZ789",
            "name": "Thermal Winter Jacket",
            "description": "Waterproof and windproof jacket with thermal insulation.",
            "sku": "SKU-WJKT789",
            "url": "http://www.company.com/product/winterjacket",
            "isInStock": false,
            "itemGroupId": "MEN-WINTER",
            "brand": {
                "name": "NorthFace",
                "logoUrl": "http://www.company.com/brand/northface.jpg"
            },
            "images": [
                "https://www.company.com/images/winterjacket1.jpg",
                "https://www.company.com/images/winterjacket2.jpg"
            ],
            "prices": [
                {
                    "price": 250.00,
                    "code": "USD"
                }
            ],
            "contents": [
                {
                    "languageTag": "en-GB",
                    "name": "Thermal Winter Jacket",
                    "description": "Stay warm and dry with our top-of-the-line thermal winter jacket.",
                    "url": "http://www.company.com/gb/product/winterjacket"
                }
            ],
            "attributes": [
                {
                    "name": "Material",
                    "stringValue": "Polyester & Nylon"
                },
                {
                    "name": "Waterproof",
                    "stringValue": "Yes"
                },
                {
                    "name": "Categories",
                    "options": [
                        {"value": "Clothing"},
                        {"value": "Outerwear"},
                        {"value": "Winter"}
                    ]
                },
                {
                    "name": "Color",
                    "options": [
                        {"value": "Navy"},
                        {"value": "Gray"}
                    ]
                }
            ]
        }
    ]
}

Response Payload

On Success

On successful update, the returned status code will be ‘202’, and the payload will contain the status message “Accepted” and a transaction ID.

{
    "transactionId": "xxxxxxxxxxxxxxxxxxxxxxx",
    "status": "Accepted"
}

For bulk insert/update the request may partially accepted. In that case the response will be,

{
    "transactionId": "xxxxxxxxxxxxxxxxxxxxxxx",
    "status": "PartiallyAccepted",
    "message": "Number of Invalid Products: 100",
    "validationMessages": [
        [
            "product[0]: Product must contain a RefId and length should not be greater than 255",
            "product[100]: Product must contain a valid Url with https or http",
        ]
    ]
}

On Error

If there are any errors, the response status code will not be ‘202’, and the relevant error messages will be provided as part of “errors” in the returned message. Here is an example -

{
"errors": {
    "products[0].RefId": [
        "Product must contain a RefId"
    ]
},
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "xxxxxxxxxxxxxxxxxxx"
}

Example Usage (JavaScript)

// Replace <PA_END_POINT> with your actual API endpoint
const apiUrl = 'https://<PA_END_POINT>/3.0/products'; 
// Replace this with your actual access token
const accessToken = 'YOUR_ACCESS_TOKEN'; 

const headers = {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${accessToken}`
};

const body = JSON.stringify({
    products: [
        {
            refId: "ABC123",
            name: "UltraBoost Running Shoes",
            description: "High-performance running shoes with responsive cushioning.",
            sku: "SKU-UBR123",
            url: "http://www.company.com/product/ultraboost",
            isInStock: true,
            itemGroupId: "MEN-SPORTS",
            brand: {
                name: "Adidas",
                logoUrl: "http://www.company.com/brand/adidas.jpg"
            },
            images: [
                "https://www.company.com/images/ultraboost1.jpg",
                "https://www.company.com/images/ultraboost2.jpg"
            ],
            prices: [
                {
                    price: 180.00,
                    code: "USD",
                    discountPrice: 150.00
                },
                {
                    price: 240.00,
                    code: "AUD"
                }
            ],
            contents: [
                {
                    languageTag: "en-AU",
                    name: "UltraBoost Running Shoes",
                    description: "Experience unmatched performance with the UltraBoost series.",
                    url: "http://www.company.com/au/product/ultraboost"
                },
                {
                    languageTag: "ja-JP",
                    name: "UltraBoost Running Shoes",
                    description: "High-performance running shoes designed for maximum comfort.",
                    url: "http://www.company.com/jp/product/ultraboost"
                }
            ],
            attributes: [
                {
                    name: "Material",
                    stringValue: "Synthetic Mesh"
                },
                {
                    name: "Weight",
                    scalarValue: 250
                },
                {
                    name: "Categories",
                    options: [
                        {value: "Clothing"},
                        {value: "Footwear"},
                        {value: "Sports"}
                    ]
                },
                {
                    name: "Color",
                    options: [
                        {value: "Black"},
                        {value: "White"}
                    ]
                }
            ]
        },
        {
            refId: "XYZ789",
            name: "Thermal Winter Jacket",
            description: "Waterproof and windproof jacket with thermal insulation.",
            sku: "SKU-WJKT789",
            url: "http://www.company.com/product/winterjacket",
            isInStock: false,
            itemGroupId: "MEN-WINTER",
            brand: {
                name: "NorthFace",
                logoUrl: "http://www.company.com/brand/northface.jpg"
            },
            images: [
                "https://www.company.com/images/winterjacket1.jpg",
                "https://www.company.com/images/winterjacket2.jpg"
            ],
            prices: [
                {
                    price: 250.00,
                    code: "USD"
                }
            ],
            contents: [
                {
                    languageTag: "en-GB",
                    name: "Thermal Winter Jacket",
                    description: "Stay warm and dry with our top-of-the-line thermal winter jacket.",
                    url: "http://www.company.com/gb/product/winterjacket"
                }
            ],
            attributes: [
                {
                    name: "Material",
                    stringValue: "Polyester & Nylon"
                },
                {
                    name: "Waterproof",
                    stringValue: "Yes"
                },
                {
                    name: "Categories",
                    options: [
                        {value: "Clothing"},
                        {value: "Outerwear"},
                        {value: "Winter"}
                    ]
                },
                {
                    name: "Color",
                    options: [
                        {value: "Navy"},
                        {value: "Gray"}
                    ]
                }
            ]
        }
    ]
});

fetch(apiUrl, {
    method: 'POST',
    headers: headers,
    body: body
})
.then(response => response.json())
.then(data => console.log('API response:', data))
.catch(error => console.error('Error uploading products:', error));

Summary

This document provides information about the Products API, including its purpose, method, URL, request body parameters, example payload, and returned payload.

The API allows creation or update of product entries with a unique reference ID and supports bulk updates for efficiency.
It uses a POST method and requires headers like Content-Type: application/json and Authorization: Bearer ACCESS_TOKEN.
The request body includes various parameters such as product details, brand information, images, prices, contents in multiple languages, and attributes.
An example payload demonstrates the structure for creating or updating products.
Upon successful update, the status code will be ‘202’ with a transaction ID; errors are handled with relevant error messages.

API Endpoint​

Request Header​

Request Parameters (Body)​

Example Request Payload​

Response Payload​

On Success​

On Error​

Example Usage (JavaScript)​

Summary​