The following examples provide step-by-step instructions to create a category and its structure with attributes, collections, and products. This example uses a furniture store selling lamps.
Use the following table to reference the category, subcategories, and products that will be created.
| Category | Sub-Categories | Products |
|---|
| Lamps | | |
| Ceiling Lamps | |
| | Atlas Pendant Ceiling Lamp |
| | Apollo Pendant Ceiling Lamp |
| Table Lamps | |
| | Hudson Table Lamp |
| | Luminary Table Lamp |
in Product Catalog, both products and categories have attributes. Each product can have multiple attributes associated with it. Because you need to add attributes to both categories and products, the first step in building the lamps category is to create the attributes needed to fulfill our objective. In this example, lamps need to have a Style attribute for all the products.
1. Create the Style Attribute with the Values Modern, Traditional, and Rustic
The product-attributes endpoint is used to create different product and category attributes. In this example, the Style attribute is created for products. This attribute differentiates lamps based on design aesthetics, such as modern or rustic. In this example the type is set to OPTIONS since multiple accepted values are added.
Note that if you set isMandatory to true in the request, anything with the Style attribute requires a value. This means if a product inherits or has the Style attribute, it must have one of the acceptedValues outlined in the request below.
Bash
curl --location 'https://api.fabric.inc/v3/product-attributes' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-fabric-tenant-id: ' \
--header 'Authorization;' \
--data '
{
"name": "Style",
"type": "OPTIONS",
"target": "PRODUCT",
"isLocalizable":false,
"localizedProperties":{},
"validation": {
"isMandatory": false,
"acceptedValues": ["Modern", "Traditional", "Rustic"],
"subType": "SINGLE",
"isManualOverwrite": false,
"isDecimal": false,
"formula": ""
}
}
'
The response includes a product attribute ID for Style. This ID is required in subsequent API requests for mapping.
2. Create a new Lamps Category
Use the categories endpoint to create a new category with the name Lamps.
Bash
--location 'https://api.fabric.inc/v3/categories' \
--header 'x-fabric-tenant-id: ' \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--data '{
"name":"Lamps"
}
'
After creating a category successfully, a response with the ID for the new category is returned. Use this ID to set up sub-categories.
3. Create the Ceiling Lamps and Table Lamps sub-categories
Use the bulk insert API for categories when you need to create more than one subcategory at a time. You must provide the parentCategoryId that you previously received in step 2 when making the parent category Lamps.
Optionally, you can also set isLocalizable to true and provide localized names.
Bash
curl --location 'https://api.fabric.inc/v3/categories/batch' \
--header 'x-fabric-tenant-id: ' \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--data '{
"categories": [
{
"parentCategoryId": "65a503418b49c6d313211159",
"name": "Ceiling Lamps",
"isLocalizable": true,
"localizedProperties": {
"en-US": {
"name": "Ceiling Lamps"
},
"es-US": {
"name": "Lámparas de techo"
}
},
},
{
"parentCategoryId": "65a503418b49c6d313211159",
"name": "Table Lamps",
"isLocalizable": true,
"localizedProperties": {
"en-US": {
"name": "Table Lamps"
},
"es-US": {
"name": "Lámparas de mesa"
}
},
}
}
],
}'
4. Map the Style attribute
With attribute mapping, you can update existing attributes and add new attributes to a category or product.
In this example, the product attribute ID corresponding to the Style attribute is added to the Lamps category, and the isMandatory flag set to true. With this setting, all products within the Lamps category must have a value corresponding to the Style attribute.
When you add an attribute to a parent category, such as Lamps, it automatically applies to all its sub-categories. In this example, Ceiling Lamps and Table Lamps are children of the Lamps category, so they inherit the mandatory Style attribute.
For mapping, use the categories endpoint and provide the ID corresponding to the Style attribute that’s returned in the response from the product-attribute endpoint.
Bash
curl --location --request PUT 'https://api.fabric.inc/v3/categories/557f1f77bcf86cd799439015' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-fabric-tenant-id: ' \
--header 'Authorization: ' \
--data '
{ "name": "Lamps",
"productAttributes": [
{
"isMandatory": true,
"id": "557f1f77bcf86cd799439015"
}
]
}
'
5. Create products and variants with attributes
This example requires four products with variants, so the products status is set to LIVE to create variants and the parentProduct field is included in the request body. The following code example shows adding the products using the bulk insert API for products, which includes the mandatory attributes values:
Bash
curl --location 'https://api.fabric.inc/v3/product-catalog/batch' \
--header 'x-fabric-tenant-id: ' \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--data '{
"products": [
{
"sku": "AGLAMPTL12",
"status":"LIVE",
"categoryId": "65a505cf8b49c6d313211187",
"isActive": true,
"type": "ITEM",
"attributes": [
{
"id": "65a503bfd97969bcbb224415",
"value": ["modern"]
},
{
"id": "6464ecfc4529ad33084c4adb",
"value": "Hudson Table Lamp"
},
{
"id" : "6464ecfc4529ad33084c4ad7",
"value": "AGLAMPTL12"
},
{
"id": "6464ecfc4529ad33084c4acb",
"value" : "https://exampleimagelink.me/assets/images/exampleimagelink.png"
},
{
"id": "6464ecfd4529ad33084c4adf",
"value" : "FALSE"
}
]
},
{
"sku": "AGLAMPTL9",
"status":"LIVE",
"categoryId": "65a505cf8b49c6d313211187",
"isActive": true,
"type": "ITEM",
"attributes": [
{
"id": "65a503bfd97969bcbb224415",
"value": ["rustic"]
},
{
"id": "6464ecfc4529ad33084c4adb",
"value": "Luminary Table Lamp"
},
{
"id" : "6464ecfc4529ad33084c4ad7",
"value": "AGLAMPTL9"
},
{
"id": "6464ecfc4529ad33084c4acb",
"value" : "https://exampleimagelink.me/assets/images/exampleimagelink.png"
},
{
"id": "6464ecfd4529ad33084c4adf",
"value" : "FALSE"
}
]
},
{
"sku": "AGLAMPCL2",
"status":"LIVE",
"categoryId": "65a505cf8b49c6d313211187",
"isActive": true,
"type": "ITEM",
"attributes": [
{
"id": "65a503bfd97969bcbb224415",
"value": ["rustic"]
},
{
"id": "6464ecfc4529ad33084c4adb",
"value": "Apollo Pendant Ceiling Lamp"
},
{
"id" : "6464ecfc4529ad33084c4ad7",
"value": "AGLAMPCL2"
},
{
"id": "6464ecfc4529ad33084c4acb",
"value" : "https://exampleimagelink.me/assets/images/exampleimagelink.png"
},
{
"id": "6464ecfd4529ad33084c4adf",
"value" : "FALSE"
}
]
},
{
"sku": "AGLAMPCL5",
"status":"Live",
"categoryId": "65a505cf8b49c6d313211187",
"isActive": true,
"type": "ITEM",
"attributes": [
{
"id": "65a503bfd97969bcbb224415",
"value": ["modern"]
},
{
"id": "6464ecfc4529ad33084c4adb",
"value": "Atlas Pendant Ceiling Lamp"
},
{
"id" : "6464ecfc4529ad33084c4ad7",
"value": "AGLAMPCL5"
},
{
"id": "6464ecfc4529ad33084c4acb",
"value" : "https://exampleimagelink.me/assets/images/exampleimagelink.png"
},
{
"id": "6464ecfd4529ad33084c4adf",
"value" : "FALSE"
}
]
},
{
"parentProduct": {
"sku": "AGLAMPCL5"
},
"sku": "GLAMPCL5",
"status": "LIVE",
"categoryId": "65a505cf8b49c6d313211187",
"isActive": false,
"type": "VARIANT",
"attributes": [
{
"id": "65a503bfd97969bcbb224415",
"value": ["modern"]
},
{
"id": "6464ecfc4529ad33084c4adb",
"value": "Green"
},
{
"id" : "6464ecfc4529ad33084c4ad7",
"value": "GLAMPCL5"
},
{
"id": "6464ecfc4529ad33084c4acb",
"value" : "https://exampleimagelink.me/assets/images/exampleimagelink.png"
},
{
"id": "6464ecfd4529ad33084c4adf",
"value" : "FALSE"
}
]
},
{
"parentProduct": {
"sku": "AGLAMPCL5"
},
"sku": "AGLAMPCL1",
"status": "LIVE",
"categoryId": "65a505cf8b49c6d313211187",
"isActive": false,
"type": "VARIANT",
"attributes": [
{
"id": "65a503bfd97969bcbb224415",
"value": ["modern"]
},
{
"id": "6464ecfc4529ad33084c4adb",
"value": "Gold"
},
{
"id" : "6464ecfc4529ad33084c4ad7",
"value": "AGLAMPCL1"
},
{
"id": "6464ecfc4529ad33084c4acb",
"value" : "https://exampleimagelink.me/assets/images/exampleimagelink.png"
},
{
"id": "6464ecfd4529ad33084c4adf",
"value" : "FALSE"
}
]
}
]
}'
Create a Sale category for Modern Style Furniture and Cyber Monday
- Create the parent collection,
Sale.
Bash
curl --location 'https://api.fabric.inc/v3/collections' \
--header 'x-fabric-tenant-id: ' \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--data '{
"isRoot": true,
"isLocalizable": false,
"name": "Sale",
}'
- Create the sub category
Current Sales. The parentCollectionID is returned from the previous response when creating the parent collection Sale.
Bash
curl --location 'https://api.fabric.inc/v3/collections/batch' \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id: ' \
--data '{
"collections": [
{
"parentCollectionId": "65a5847b8b49c6d313211476",
"name": "Current Sales",
"isLocalizable": false,
"isRoot": false,
"isLeaf": false
}
]
}'
- Create the
Modern Style Furniture and Cyber Monday categories.
Bash
curl --location 'https://api.fabric.inc/v3/collections/batch' \
--header 'Authorization: ' \
--header 'Content-Type: application/json' \
--header 'x-fabric-tenant-id: ' \
--data '{
"collections": [
{
"parentCollectionId": "65a58a5b8b49c6d313211486",
"name": "Modern Style Furniture",
"isLocalizable": false,
"isRoot": false,
"isLeaf": false,
"categoryIdsIncluded": [
"65a503418b49c6d313211159"
]
},
{
"parentCollectionId": "65a58a5b8b49c6d313211486",
"name": "Cyber Monday",
"isLocalizable": false,
"isRoot": false,
"isLeaf": false,
"categoryIdsIncluded": [
"65a503418b49c6d313211159"
]
}
]
}'
Optionally, you can include products in a sale tab by filtering for specific attributes using productAttributeFilters.
"productAttributeFilters": [
{
"attributeId": "78184766610c0e32a86d8757",
"condition": "EQUALS",
"value": 2
}
]
Error Handling
For effective error handling, refer to the API documentation which outlines standard HTTP error codes, such as 400 (Bad Request), 404 (Not Found), and 500 (Internal Server Error).
Next Steps
Once the above steps are completed, you are all set with the basic setup. You may proceed to fully utilize all features and capabilities available to you. Refer to the Related Resources for additional information.
