bitzorcas
中 EN

Reference

Catalog module

Product/service catalog — plan definitions, add-on offerings, entitlement mappings, and configurable catalog items for SaaS subscription management.

Last updated

The Catalog module provides a flexible product/service catalog that feeds the billing system. It manages plan definitions, add-on offerings, entitlement mappings, and configurable catalog items.

Endpoints

EndpointMethodDescription
/api/catalog/itemsPOSTCreate catalog item
/api/catalog/itemsGETList catalog items
/api/catalog/items/{id}GETGet item details
/api/catalog/plansPOSTCreate plan
/api/catalog/plansGETList plans
/api/catalog/add-onsPOSTAdd add-on to plan
/api/catalog/offerings/{tenantId}PUTSet tenant catalog offering
/api/catalog/entitlements/{planId}POSTMap entitlement to plan

Architecture

CatalogEndpoints (Minimal API)
       │
       ▼
CatalogService
       │
       ├── ICatalogRepository → SqlSugarCatalogRepository
       ├── ICatalogEntitlementMappingStore
       └── ICatalogEventPublisher → NullCatalogEventPublisher

CatalogItem entity

public class CatalogItemEntity : TenantSoftDeleteEntityBase
{
    public string Name { get; set; }
    public string Description { get; set; }
    public string ItemType { get; set; }  // Plan, AddOn, Feature, Entitlement
    public string? Metadata { get; set; }  // JSON configuration
    public bool IsActive { get; set; }
}

Entitlement mapping

Plan → CatalogOffering → EntitlementMapping → Quota Key
ConceptDescription
Catalog ItemIndividual product/feature definition
PlanBundle of entitlements at a price point
Add-OnOptional feature addable to any plan
Entitlement MappingLinks catalog items to quota keys
Catalog OfferingPer-tenant assigned plan + add-ons

Plans and add-ons

Plans define the base subscription tier; add-ons extend functionality:

Free Plan          → { storage: 1GB, tickets: 10, chat: 1 channel }
Pro Plan           → { storage: 100GB, tickets: 100, chat: 10 channels }
Enterprise Plan    → { storage: unlimited, tickets: unlimited, chat: unlimited }
+ Extra Storage    → { storage: +50GB }
+ Priority Support → { tickets: priority queue }

See also