Customer Categories

Customer categories allow you to control which products specific customers can see. This is particularly useful for B2B scenarios where different customers or customer segments should have access to different product catalogs.

Overview

Customers can have two types of category restrictions:

When a customer searches for products:

• If they have include categories, only products in those categories are shown
• Exclude categories are always filtered out, regardless of include settings

How It Works

Product Search with CustomerId
        │
        ▼
┌───────────────────────────────────────────────────────────────┐
│  Load Customer                                                 │
│  ├── AssortmentIncludeProductCategoryIds: ["electronics"]     │
│  └── AssortmentExcludeProductCategoryIds: ["restricted"]      │
└───────────────────────────────────────────────────────────────┘
        │
        ▼
┌───────────────────────────────────────────────────────────────┐
│  Apply Category Filter                                         │
│  ├── Include: Only show products in "electronics" category    │
│  └── Exclude: Hide products in "restricted" category          │
└───────────────────────────────────────────────────────────────┘
        │
        ▼
    Filtered Results

Customer Configuration

Business Customer

{
  "customerId": "acme-corp",
  "customerType": "business",
  "name": "ACME Corporation",
  "assortmentIncludeProductCategoryIds": [
    "industrial-equipment",
    "safety-gear"
  ],
  "assortmentExcludeProductCategoryIds": [
    "consumer-products"
  ]
}

Private Customer

{
  "customerId": "john-doe",
  "customerType": "private",
  "name": "John Doe",
  "assortmentIncludeProductCategoryIds": ["vip-products"],
  "assortmentExcludeProductCategoryIds": []
}

API Operations

Set Customer Categories

PATCH /api/BusinessCustomers/PatchBusinessCustomer
Content-Type: application/json
 
{
  "customerId": "acme-corp",
  "assortmentIncludeCategoryIds": ["industrial-equipment", "safety-gear"],
  "assortmentExcludeCategoryIds": ["consumer-products"]
}

Or for private customers:

PATCH /api/PrivateCustomers/PatchPrivateCustomer
Content-Type: application/json
 
{
  "customerId": "john-doe",
  "assortmentIncludeCategoryIds": ["vip-products"],
  "assortmentExcludeCategoryIds": []
}

Remove Category Restrictions

Send an empty array to remove restrictions:

PATCH /api/BusinessCustomers/PatchBusinessCustomer
Content-Type: application/json
 
{
  "customerId": "acme-corp",
  "assortmentIncludeCategoryIds": [],
  "assortmentExcludeCategoryIds": []
}

Search Behavior

Omnium UI (Automatic Filtering)

When searching products through the Omnium UI (e.g., adding products to a cart), category restrictions are applied automatically based on the customer linked to the cart. No additional steps are needed.

Public API Usage

When using the public API, you must apply category restrictions yourself. The recommended flow is:

1. Fetch the customer to get their category restrictions:

GET /api/BusinessCustomers/{customerId}

From the response, read assortmentIncludeProductCategoryIds and assortmentExcludeProductCategoryIds.

2. Pass the categories in the product search request:

POST /api/Products/SearchProducts
{
  "customerId": "acme-corp",
  "productCategoryIds": ["industrial-equipment", "safety-gear"],
  "excludedProductCategoryIds": ["consumer-products"],
  "query": "equipment"
}

User-Specified Categories

If the user specifies their own categories in the search request:

How Filtering Works

Omnium UI (Automatic)

When a product search is performed through the Omnium UI with a customerId:

1. The customer is loaded from the database
2. If the search request has no category filter AND the customer has include categories:
   • The customer's include categories become the search filter
3. If the customer has exclude categories:
   • These are always applied (cannot be overridden by the search request)

Public API (Manual)

When using the public API, filtering is based only on the parameters you pass in the search request. The API does not automatically look up the customer's category restrictions. Your integration must:

1. Fetch the customer's assortmentIncludeProductCategoryIds and assortmentExcludeProductCategoryIds
2. Pass them as productCategoryIds and excludedProductCategoryIds in the search request

Use Cases

B2B Customer Tiers

Different customers see different product ranges:

Bronze Tier Customer:

{
  "assortmentIncludeProductCategoryIds": ["basic-products"]
}

Gold Tier Customer:

{
  "assortmentIncludeProductCategoryIds": [
    "basic-products",
    "premium-products",
    "exclusive-products"
  ]
}

Industry-Specific Catalogs

Customers in different industries see relevant products:

Healthcare Customer:

{
  "assortmentIncludeProductCategoryIds": [
    "medical-equipment",
    "sanitization",
    "safety-gear"
  ]
}

Manufacturing Customer:

{
  "assortmentIncludeProductCategoryIds": [
    "industrial-machinery",
    "raw-materials",
    "safety-gear"
  ]
}

Restricted Products

Hide certain products from specific customers:

Standard Customer:

{
  "assortmentExcludeProductCategoryIds": [
    "restricted",
    "hazardous",
    "licensed-only"
  ]
}

Combining with Other Assortment Controls

Customer categories work alongside other assortment mechanisms:

Example: A product must:

1. Be in the customer's allowed categories
2. AND be in the current store's assortment
3. AND have matching assortment codes (if customer is restricted)
4. AND be active with valid dates

Best Practices

Category Granularity

Design categories with customer restrictions in mind:

• Create clear separation between restricted and unrestricted categories
• Use parent categories for broad restrictions
• Use child categories for fine-grained control

Testing Customer Views

To test what a customer sees:

1. Create a test search request with the customer's ID
2. Compare results with and without ignoreCustomerAssortment
3. Verify expected products are visible/hidden

Bulk Customer Updates

When updating many customers with the same restrictions, consider:

• Creating a customer group with default category settings
• Using API bulk operations
• Importing category assignments via data integration

Troubleshooting