Catalogs are at the core of your business: they list all the products you offer to shoppers and store details about every one of your products such as: name, price, product code, images, etc.
Types of Catalogs
There are two types of catalogs:
- Master Catalogs: Specific to your tenant and contain all the products in your child catalogs that belong to them, which enables you to share products across all child catalogs.
- Catalogs: Specific to each of your sites or storefronts and only contain the products in them that you wish to sell in their associated storefronts.
Do not delete a master catalog from your tenant if you only have one master catalog. If you need to delete a master catalog, ensure that you have an additional master catalog before deleting the master catalog. If you delete the only master catalog in your tenant, the tenant will no longer function properly and you will need to have an entire new tenant provisioned.
Catalog Example
Imagine that your business includes a brick and mortar store in Austin, a kiosk in San Antonio, and a website, and you sell the following products:
| Product | Location Available |
|---|---|
| Shirt | Austin store and website |
| Pants | Austin store and website |
| Skirts | Austin store and website |
| Sunglasses | San Antonio kiosk only |
| Bags | Austin store and website |
Given this situation, you would configure your catalogs in the following way:
| Catalog Name | Catalog Type | Description |
|---|---|---|
| Master Apparel Catalog | Master catalog | Includes all of your products, including all the shirts, pants, skirts, sunglasses, and bags you sell. |
| Austin Store Catalog | Catalog | Includes a subset of all your products. You only sell shirts, skirts, pants, and bags in your Austin store. |
| San Antonio Kiosk Catalog | Catalog | Includes a limited subset of the products that you sell at your kiosk. You only sell sunglasses at the kiosk. |
| Website Catalog | Catalog | Includes a subset of all products that you sell online. You only sell shirts, pants, skirts, and bags on your website. |
Multi-Locale Catalogs
If you are using an implementation that supports this feature, then multiple locales can be enabled for a single master or child catalog. This allows you to easily localize the same product information across different languages.
Each master catalog will have a default locale that all of the main configurations are made on, such as product pricing. You will be able to switch to any of the supported locales when viewing a catalog's product, product attribute, category, and discount configuration pages. Then you can change certain language-specific fields, such as product names and descriptions, for that locale. When interfacing with APIs, a localizedContent object will contain these details for each locale. See the Catalog Admin API documentation for product, attribute, category, and discount request models with this object.
You cannot have two child catalogs that are the same locale (such as en-US) but have different descriptions within the same master catalog. Additionally, all locales of a catalog must use the same currency—different currencies require separate catalogs.
Supported Implementations
As of May 2024, multi-locale catalogs is only available to European implementations for stability testing. When this feature is fully released, it will be available out-of-the-box for all new implementations.
If your implementation was built prior to May 2024, then you are using the previous version of the Product API without localized content and will need to contact Kibo Support to be upgraded if you want to use this feature.
Once upgraded, calls to the Products, Attributes, Categories, and Discounts APIs will require localizedContent by default. If you need to manage older product data that hasn't been rewritten to the new model, include an x-api-version header set to "1" in your API request. This will call the original version of the API that supports your existing products without localization.
Internal-Only: Migration Guidelines
To switch an existing client to the new version of these APIs, change their catalog-admin-products-DefaultApiVersion tenant attribute from "1" to "2" and that will be their new default going forward. Refer to the following example for some configuration guidelines and best practices.
Example Scenario:
- A master catalog's default locale is en-US.
- Catalog 1 has a default locale of en-US and is used for the English site.
- Catalog 2 has a default locale of fr-FR and is used for the French site.
You can either create a new master catalog and add all supported locales there, or use custom code to populate values for other supported locales:
- Supported locales should already be populated with the migration and on the product database. Take an existing master catalog and pick an existing child catalog that has the same default locale (Catalog 1).
- Products and attributes should already be populated due to migration during deployment. For categories, manually populate the alternate locale values by taking the French locale values from Catalog 2 and populating them in Catalog 1. You can perform lookups based on the category code (assuming they match between catalogs) to methodically retrieve and copy over the French values.
- Discounts are more difficult to move over if the discount name or threshold messages are required to be shown in French.
- If they do not require localization, simply make sure to take the delta discounts from Catalog 2 and create them on Catalog 1.
- If text does need to be localized, there are no discount codes to match between catalogs. Each tenant's circumstances are unique and require custom logic. For instance, if the discount name is never displayed and the name is the same between both catalogs, then you might be able to migrate the threshold messages.
Even if a discount doesn’t have a name or threshold message in fr-FR, it will still apply on the French site. It just won’t show any localized text for fr-FR.
- Create a new French site pointing to Catalog 1 with fr-FR as the locale. The site-specific code will have to be modified.
- Starting using the V2 payload for create/update/delete operations, populating the
localizedContent. - For products, you can use the
x-api-versionheader to control whether you want the payload to represent the schema for V1 or V2.
For more details, refer to CAT-4688 and related tickets.