Developer Guide

​

Getting Started with fabric Product Catalog API

fabric Product Catalog API supports CRUD operations related to Product Catalog. This service is designed to provide low latency reads and search functionalities for the storefront. It supports event-driven updates to ensure the data is always up-to-date without manual intervention, efficient cache management for faster data retrieval, and scalability to handle high volumes of traffic.

This guide provides step-by-step instructions to help you get started with fabric Product Catalog API, from initial setup to basic usage.

​

Target Audience

• Solution Integration (SI) partners responsible for configuring the Product Catalog for e-commerce.
• Third-party developers who set up Product Catalog on behalf of merchants.
• The fabric developers who work with Product Catalog.

​

Knowledge and Skill Requirements

The target audience should:

• Understand REST APIs, in the context of e-commerce.
• Get familiar with fabric APIs.
• Know the concepts related to Product Catalog.
• Create a strategy to migrate from a third-party product information management system if applicable.
• Understand caching strategies and technologies.
• Have access to development tools capable of interacting with HTTP-based APIs, such as Postman or cURL for testing.

We also recommend you to:

• Maintain a list of attributes that need to be assigned to products and categories.
  • Identify the mandatory and optional attributes.
• Develop a strategy for organizing products within a hierarchical tree structure of categories and collections.
• Create a product list consisting of individual items, variants, and bundles of items and variants.

​

Workflow

The following workflow diagram illustrates the step-by-step interaction process with the Product Catalog API:

The following steps outline the process:

1. Create attributes that can be assigned to categories and associated products.
2. Map fabric-mandatory attributes with merchant-defined attributes.
3. Create categories as the primary organizational structure.
4. Assign attributes to categories.
5. Create collections to display products on storefronts and support storefront-specific use cases, including promotions.
6. Add products, such as individual items, variants, and bundles of items and variants.

​

Configuring Product Catalog

To configure Product Catalog:

​

Prerequisites

You must have the following:

• Access and Permissions Setup
  • Ensure that you have Admin or Editor role to set up Product Catalog. For more information about the roles and permissions offered through fabric Identity service, see the Role-based Access Control (RBAC) section.
    • Click here to understand the roles and permissions supported through Role-based Access Control (RBAC) offered through fabric Identity service.
  • Use the V3 version of the Product Catalog API.
• Authentication and Security Protocols
  • Ensure that you have a valid Authorization Token to provide in the header. For additional information, see the Client S2S Authorization token guide.

​

Procedure

Use this procedure to configure Product Catalog. The API collections for the endpoints are:

• Postman collection for attributes.
• Postman collection for categories.
• Postman collection for products.

1. Create attributes using one of the following methods:
   • Individually: Create a new attribute using the Create attribute endpoint. By specifying the target in the request body as a product or category, you can assign the attribute to a product or a category, respectively.
   • Bulk Import: Import multiple attributes through bulk import APIs. For more information, see the bulk import guide.
   • (Optional) Create attribute groups using the Create attribute groups endpoint and group relevant attributes. The attribute groups can then be assigned to products.
2. Map the mandatory fabric attributes, such as sku, title, image, and active status, to the corresponding attribute names provided by the merchant. To create new mapping or update an existing mapping, use the Update attribute endpoint.
3. Create categories using one of the following methods:
   • Individually: Create a new category using the Create category endpoint. A root category is created by default and can’t be modified.
   • Import Multiple Categories: Add multiple new categories using the Create multiple categories endpoint. You can add up to 25 categories.
   • Bulk Import: Add multiple categories (more than 25) through bulk import APIs. For additional information, refer to the bulk import guide. You can add other category IDs to categoryIdsIncluded which automatically includes a categories catalog of items. Similarly, you can exclude categories using categoryIdsExcluded.
4. Assign attributes to categories using the Create category and Partially update category endpoint. The attributes of a category automatically cascade to all products associated with that category.
5. (Optional) Create collections to display products on storefront using the Create collections endpoint.
6. Add products, which may be items, variants, and bundles, using one of the following methods:

   • Add Item: Add items using the following methods:

     • Individually: Add a single item using the Add product endpoint and specify the type as item.
     • Add Multiple items: Add multiple items using the Add products endpoint and specify the type as item. You can add up to 25 items in a single request.
     • Bulk Import: Import multiple products through bulk import APIs. For additional information, refer to bulk import guide.

   • Add Variants: For creating variants for a product, you must set the product’s status flag to LIVE. If a product status is DRAFT, variants are treated as separate products. Add variants using the following methods:

     • Individually: Add a single variant using the Add product endpoint and specify the type as variant.
     • Add Multiple Variants: Add multiple variants using the Add Products endpoint and specify the type as variant. You can add up to 25 variants.
     • Bulk Import: Import variants using the bulk import APIs. For additional information, refer to the bulk import guide.
       Note: To add a variant, its parentProduct must be in published or draft status. Initially, the type remains as item until the parent is published. Once the parent is published, the type is updated to variant. Additionally, both the parent and its children should belong to the same category and channel.

   • Add Bundles: Add bundles using the following methods:

     • Individually: Add a single bundle using the Add Product endpoint and specify the type as bundle.
     • Add Multiple Products: Add multiple bundles using the Add Products endpoint and specify the type as bundle. You can add up to 25 bundles.
     • Bulk Import: Import bundles using the bulk import guide API. When bulk importing attributes, specify their corresponding type and subtype in the template. The following list shows the Attribute types and their corresponding Attribute sub types:
       • Serial: None
       • Date-Time: None
       • Boolean: None
       • Number: None
       • Text: Small text
       • Text: Text area
       • Text: HTML
       • Options: Single
       • Options: Multiple

     Note: When creating a bundle, make sure to specify the bundleProducts. Ensure the individual items or their variants, which you intend to include in the bundle, already exist in the system.

​

Import Product Data Through Bulk Import

The following diagram illustrates the step-by-step process to bulk import attributes, categories, collections, items, variants, and bundles:

Take the following steps to bulk import:

1. Download the template based on the type, which could be items, variants, bundles, attributes, categories, or collections. A CSV template with header columns is returned in the response. You can add required data in the template and save the file in your local system.
   The following code sample provides an example for the template:

Bash

curl --request POST \
     --url https://api.fabric.inc/v3/product-templates/actions/generate \
     --header 'accept: text/csv' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "ITEM",
  "categoryId": "648014741adc8a9de14e1a68",
  "locale": "en-US"
}
'

The following code sample provides an example to bulk import attributes:

Bash

curl --request POST \
     --url https://api.fabric.inc/v3/product-templates/actions/generate \
     --header 'accept: text/csv' \
     --header 'content-type: application/json' \
     --data '{"type":"ATTRIBUTE"}'

1. Retrieve the AWS S3 bucket URL used to upload the import file by using the Create file object and get upload location endpoint.
   The following code sample provides an example to retrieve the upload URL to import a file:

Bash

curl --request POST \
    --url https://api.fabric.inc/v3/product-files \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --data '
{
 "type": "ITEM_VARIANT_EXPORT",
 "name": "bulk_import_123345677788999.csv",
 "locale": "en-US"
}
'

1. Make a PUT request with the upload URL, returned in the response of the step 2, to upload the updated CSV file from your local system.
2. Download one or more previously imported or exported files, including error files, use the Get files available for a merchant endpoint.
   The following code sample provides an example:

Bash

curl --request GET \
    --url 'https://api.fabric.inc/v3/product-files?offset=0&limit=10' \
    --header 'accept: application/json'

1. To view the status of previously imported or exported files, use the Get jobs endpoint.
   The following code sample provides an example to retrieve the import history:

Bash

curl --request GET \
     --url 'https://api.fabric.inc/v3/product-jobs?offset=0&limit=10' \
     --header 'accept: application/json'

​

Examples

The following examples provide step-by-step instructions to create a category structure, attributes, collections, and products for Lamps.

Use the following table to reference the category, subcategories, and products that will be created by following along.

In the fabric Product Catalog API Service, 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

--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

1. 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",
    
}'

1. 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
    }
  ]
}'

1. 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 in Product Catalog V3, 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 use all features and capabilities available to you. Refer to the Related Resource for additional information.

​

Related Resources

For additional information, refer to the following:

• Product Catalog FAQs.
• Sample store to view the given product organization.
• User guide for Product Catalog in Copilot.
• API reference for all operations related to attributes
• API reference for all operations related to categories.
• API reference for all operations related to collections.
• API reference for all operations related to products based on SKU or product ID.

​

Contact

If you have questions that aren’t answered in the existing documentation, contact fabric support.