Configuring Product Catalog

Setting up Product Catalog involves defining product attributes, structuring categories, and managing products, variants, and bundles. This ensures a scalable and well-organized catalog that aligns with your business needs.

This topic covers the key steps to configure Product Catalog.

​

Prerequisites

Ensure you have the following:

• Administrator or editor privileges to fabric Product Catalog. For more information, see Role-Based Access Control.
• A valid Authorization Token to provide in the header.

​

Workflow Diagram

The following diagram illustrates the required steps to set up Product Catalog.

​

Procedure

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

1. Before using Product Catalog APIs, users must authenticate API requests with a valid authorization token. Authentication is performed through API apps, which generate API keys to validate requests. Use system apps for backend integrations and user apps for authentication tied to individual or user credentials.

2. 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 at once through bulk import APIs. For more information, see the bulk import guide.
   • (Optional) Create attribute groups using the create attribute groups endpoint to group related attributes for easier management and assignment.

3. Map the mandatory fabric attributes, such as sku, title, image, and active, to the corresponding attribute names provided by the merchant. Use the update attribute mapping endpoint to create or update these mappings.

4. Create categories to organize products into a structured hierarchy using one of the following methods:

   • Individually: Use the create category endpoint to add a single category. A default root category is created automatically and can’t be modified.
   • Batch create: Use the create multiple categories endpoint to add up to 25 categories in one request.
   • Bulk Import: For larger imports, use the bulk import APIs as directed in the bulk import guide. Use the categoryIdsIncluded and categoryIdsExcluded fields to control which categories are included or excluded in a catalog.

5. Assign attributes to categories using the create category or partially update category endpoints. When attributes are assigned to a category, they automatically apply to all products within that category.

6. Add items to your catalog using one of the following methods:

   • Individually: Use the add product endpoint and specify the type as item.
   • Batch create: Add up to 25 items at once using the add products endpoint.
   • Bulk Import: Import a large number of items with bulk import APIs. For details, see the bulk import guide.

7. Add variants to existing items using one of the following methods:

   • Individually: Use the add product endpoint and set the type to variant.
   • Multiple variants: Add up to 25 variants using the same add Products endpoint.
   • Bulk Import: Use bulk import APIs to import variants in large volumes. For details, see the bulk import guide.
   If the parent product is in DRAFT status, variants are treated as separate items until the parent is published. Parent and child products must share the same category and channel.

8. Add bundles using one of the following methods:

   • Individually: Use the add Product endpoint with the type set to bundle.
   • Multiple bundles: Add up to 25 bundles using the add Products endpoint.
   • Bulk Import: Use bulk import APIs to add bundles at scale. For details, see the bulk import guide.

9. (Optional) Use the create collections endpoint to organize products for specific storefront displays. Collections allow you to group products across categories based on shared attributes or promotional needs—ideal for seasonal campaigns, featured product sets, or curated shopping experiences.

10. Assign attributes to collections. After creating a collection, assign relevant attributes that will be used to filter the products displayed within it. This ensures that collection rules, such as “color” is “red” or “price” is under “$100,” can be evaluated correctly. Use the get attributes groups of a category endpoint to view attribute groups and confirm the correct attributes are available for use in filtering logic.

​

Bulk Importing Product Data

The Product Catalog API supports bulk import for attributes, categories, collections, items, variants, and bundles. This allows developers to efficiently manage large datasets and speed up catalog setup. The process involves downloading a CSV template, populating it with product data, uploading it to fabric’s storage system, and triggering a background job to process the file.

For best practices and formatting guidance, see the [data ingestion] (/v3/product-catalog/data-ingestion) guide.

When bulk importing attributes, be sure to specify the correct attribute type and subtype in the import template. For the full list of supported types and how they’re used, see Product Attributes.

The following diagram illustrates the import process.

​

Procedure

1. Download the template for the data type you want to import, whether item, variant, bundle, attribute, category, or collection. This template contains header columns required for successful data ingestion. Fill out the template locally with your product data.

Example: Generate an import template for items:

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"}'

2. Use the create file object and get upload location endpoint to generate an AWS S3 bucket URL for uploading your completed import file. This URL ensures secure, direct file upload to fabric’s storage.

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"
}
'

3. Use the pre-signed upload URL returned in step 2 to make a put request and upload your completed CSV file from your local system.

4. Retrieve previously uploaded or exported files—including error logs—using the get files available for a merchant endpoint.

Bash

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

5. Use the get jobs endpoint to monitor the status of previous import or export operations, including completion or failure messages.

Bash

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