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 the creation of new product entries, or updates to existing products, in the catalog.
Each product is identified by a unique reference ID (refId), and the API supports bulk updates.
- Maximum 1000 products are allowed per API call.
- All fields and attributes must be supplied. Any missing fields will be set to Null/Empty.
-
Method:
POST -
URL:
https://<PA_END_POINT>/3.0/products -
Headers:
Content-Type: application/jsonAuthorization: Bearer ACCESS_TOKEN
-
Request Body Parameters:
-
products (array)[REQUIRED]: A list of product objects, each containing --
refId (string)[REQUIRED]: A unique identifier for the product. -
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)[REQUIRED]: The product name. -
description (string): A detailed description of the product. -
sku (string): Stock Keeping Unit, a unique identifier for each product variant. -
url (string)[REQUIRED]: The URL to the product page. -
isInStock (boolean)[REQUIRED]: 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): URLs to images of the product. -
prices (array of objects): 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 objects): 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 objects): 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): Thevalueoptions of the attribute. Eachvaluewill contain the following properties -value (string): The option value.
-
-
-
-
Here is an example 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"}
]
}
]
}
]
} -
Returned Payload:
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"
}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"
}
Here’s an example code snippet using JavaScript’s Fetch API:
// 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.