Catalogs
Catalogs help you store and manage business data for marketing automation. This guide explains the types of catalogs available and how to use catalog data in campaigns and recommendations.
What are catalogs
A catalog is a lookup table with one primary key item_id that stores and manages business data for marketing automation. Ecommerce websites typically use catalogs to store products and related information, while publishing businesses use catalogs for articles and section details.
Catalog types
Bloomreach offers two types of catalogs:
General catalogs
A flexible lookup table for your project where item_id is the only required attribute as the primary key. Define all other attributes based on your business needs.
Product catalogs
Designed to store ecommerce product information with a predefined data structure that helps Bloomreach identify key product details for recommendations, inventory management, and stock level calculations.
Create and manage catalogs
The way you create and manage catalogs depends on your integration. Non-Data hub integrations use the legacy catalogs system.
Data hub integrations
Catalogs include the following:
Product catalogs
If you're Data hub enabled, create and manage product catalogs in Data hub using item collections. Once you create a product catalog in Data hub and connect it to your project as a destination, the catalog automatically appears in your catalogs listing.
General catalogs
Create general catalogs directly within the Catalogs application. General catalogs with Data hub integrations offer features including mutable schemas and searchable settings that you can modify after creation.
Non-Data hub integrations
Create and manage both product and general catalogs directly in the project using imports and the Catalog API. For non-Data hub integrations, you can’t change the catalog schema or searchable attributes after creation.
Key differences
Learn about the key differences in capabilities between the Data hub catalogs and legacy catalogs.
Recommended reserved product catalog attributes
The table below lists the recommended reserved product catalog attributes. These attributes have special meaning in Bloomreach and enable features such as recommendations and inventory management.
| Attribute | Attribute Name | Type | Description | Example Value |
| Product ID | product_id | string | Base product identifier (ignores variants). | "SHIRT123" |
| Item ID | item_id | string | Unique identifier of your product variants (SKU, EAN - considering sizes, colors). Note: To enable edits using the Catalog API, use item_id values that don't contain /. Due to endpoint decomposition, edit attempts won't work with item_id values containing /, which also affects edits via the platform UI. | "SHIRT123-BLK-L" |
| Title | title | string | Product name. | "Black fitted crew neck t-shirt" |
| Description | description | string | Product description. | "Comfortable cotton t-shirt..." |
| Active | active | boolean | Product availability status. | true |
| Brand | brand | string | Product brand. | "Nike" |
| Category IDs | category_ids | list | Internal category identifiers. | [12345, 67890] |
| Category Level 1 | category_level_1 | string | Top-level category name. | "Shoes" |
| Category Level 2 | category_level_2 | string | Second-level category name. | "Athletic" |
| Category Level 3 | category_level_3 | string | Third-level category name. | "Running" |
| Category Path | category_path | string | Full category hierarchy. | "Shoes | Athletic | Running" |
| Color | color | string | Main product color. | "red" |
| Gender | gender | string | Target gender. | "Male", "Female", "Unisex" |
| Image | image | string | Main product image URL. | http://example.com/image.jpg |
| Lead Time | lead_time | string | Restocking time. | "7" |
| Supplier | supplier | string | Supplier identifier. | "SUPP123" |
| Size | size | string | Product size. | "XL", "12" |
| URL | url | string | Direct product URL. | http://example.com/product |
| Stock Level | stock_level | integer | Current inventory quantity. | 42 |
| Cost Per Unit | cost_per_unit | float | Product cost before margin. | 15.99 |
| Discount Percentage | discount_percentage | float | Percentage discount. | 50.0 |
| Price | price | float | Final customer price. | 29.99 |
| Returned Products | returned_products | string | Number of returns. | "5" |
| Date Added | date_added | timestamp | First inventory date. | 1709078400 |
Data mapping
Non-Data hub integrations
- If your workspace isn’t Data hub enabled, ensure you map the catalog attributes during the initial catalog import in Data & Assets → Imports.
- Then, use Data & Assets → Data manager → Mapping to choose the required main catalog and map the reserved attributes.
See the legacy catalogs setup guide.
Data hub integrations
If your account has Data hub enabled, how you configure catalog attributes depends on the catalog type.
Product catalogs
If your main product catalog is managed via Data hub item collection:
Map product attributes in Data hub
- Go to the Schema tab to configure how record fields map to item attributes (including system attributes). See Configure schema.
- Set item identifier. This corresponds to the item_id.
Choose main catalog and control searchable fields in Engagement destination
- After you create an Engagement destination for the item collection, Data hub keeps the product catalog in sync.
- Use Data & Assets > Data manager > Mapping to choose the required main catalog.
- To change which attributes can be used as filters in recommendations and campaigns, go to Data & Assets > Catalogs > [The product catalog] > Attributesand adjust the Searchable settings. Update these at any time without recreating the catalog. See the Data hub catalogs setup guide.
Required mappings for product-based use cases
When setting up use cases or recommendations that reference product data, confirm that the reserved attributes reference the Data hub system attribute listed below.
| Reserved attribute | Data Hub system attribute |
| item_id | Item identifier set in item collection schema. |
| image | large_image |
| price | price |
| original_price | original_price |
| title | title |
| url | url |
| active status | active |
General catalogs (Data hub catalogs)
If you use general catalogs:
- Create and manage general catalogs by going to Data & Assets → Catalogs and create a catalog with type General.
- Configure schema and searchable fields using the catalog’s Schema tab to define attributes and choose which ones are searchable. Change these settings at any time without recreating the catalog.
See the Data hub catalogs setup guide.
User access
Manage catalog permissions through roles in Access Management > Roles. Assign appropriate roles to perform catalog operations.
Full catalog management
Users with Project Developer/Admin, Imports Admin, or Campaigns Editor/Admin roles have complete control over catalogs.
Permissions
- Create, delete, and modify catalogs along with their records, configuration, and schema.
- Create, modify, run, and delete catalog imports.
- View all catalog components, including items, records, schema, jobs, and imports.
View-only access
Users with Campaigns Viewer, Weblayers Viewer/Editor/Publisher, Email Campaigns Viewer/Editor/Publisher, SMS Campaigns Viewer/Editor/Publisher, Scenarios Viewer/Editor/Publisher, Customers Viewer/Editor/Consent Editor, Managed Endpoints Viewer/Editor/Publisher, or Recommendation Viewer/Editor roles can view all catalogs and their components.
Permissions
View catalog items, item attributes, records, record fields, configuration, schema, jobs, and imports.
Limitations
- Maximum number of catalogs per project: 50.
- Maximum number of searchable attributes per catalog: 40.
- Maximum number of items within one catalog: 6,000,000 for legacy catalogs; 1,000,000 for Data hub catalogs.
- Maximum length of a catalog item value is 28,672 bytes (legacy catalogs). If you exceed this, shorten the value or split the property into two shorter ones.
- Maximum number of attributes in a catalog or single item: 260 (Data hub catalogs only).
Downloading and exporting catalogs isn't possible. If your use case requires a higher limit, contact Bloomreach Support to discuss your requirements. After review, individual rate limits can be adjusted on a case-by-case basis.
Note
Catalogs with no usage in the previous 90 days (no access from the application and no import) are automatically deleted. All respective scenarios remain editable.
Personally identifiable information
Catalogs should never contain personally identifiable information (PII) such as emails or phone numbers.
Updated 11 days ago