Upload folder using huggingface_hub (part 9)

openmeter/productcatalog/adapter/transaction.go

@@ -0,0 +1,34 @@
+package adapter
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+
+	"github.com/openmeterio/openmeter/openmeter/ent/db"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	"github.com/openmeterio/openmeter/pkg/framework/entutils"
+	"github.com/openmeterio/openmeter/pkg/framework/transaction"
+)
+
+// We implement entuitls.TxUser[T] and entuitls.TxCreator here
+// There ought to be a better way....
+
+func (e *featureDBAdapter) Tx(ctx context.Context) (context.Context, transaction.Driver, error) {
+	txCtx, rawConfig, eDriver, err := e.db.HijackTx(ctx, &sql.TxOptions{
+		ReadOnly: false,
+	})
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to hijack transaction: %w", err)
+	}
+	return txCtx, entutils.NewTxDriver(eDriver, rawConfig), nil
+}
+
+func (e *featureDBAdapter) WithTx(ctx context.Context, tx *entutils.TxDriver) feature.FeatureRepo {
+	txClient := db.NewTxClientFromRawConfig(ctx, *tx.GetConfig())
+	return NewPostgresFeatureRepo(txClient.Client(), e.logger)
+}
+
+func (e *featureDBAdapter) Self() feature.FeatureRepo {
+	return e
+}

openmeter/productcatalog/addon.go

@@ -0,0 +1,338 @@
+package productcatalog
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"maps"
+	"slices"
+	"time"
+
+	"github.com/invopop/gobl/currency"
+	"github.com/samber/lo"
+
+	"github.com/openmeterio/openmeter/pkg/clock"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+const (
+	AddonStatusDraft    AddonStatus = "draft"
+	AddonStatusActive   AddonStatus = "active"
+	AddonStatusArchived AddonStatus = "archived"
+	AddonStatusInvalid  AddonStatus = "invalid"
+)
+
+type AddonStatus string
+
+func (s AddonStatus) Values() []AddonStatus {
+	return []AddonStatus{
+		AddonStatusDraft,
+		AddonStatusActive,
+		AddonStatusArchived,
+	}
+}
+
+func (s AddonStatus) Validate() error {
+	if !slices.Contains(s.Values(), s) {
+		return fmt.Errorf("invalid addon status: %s", s)
+	}
+	return nil
+}
+
+var (
+	_ models.Validator          = (*AddonMeta)(nil)
+	_ models.Equaler[AddonMeta] = (*AddonMeta)(nil)
+)
+
+type AddonMeta struct {
+	EffectivePeriod
+
+	// Key is the unique key for Add-on.
+	Key string `json:"key"`
+
+	// Version
+	Version int `json:"version"`
+
+	// Name
+	Name string `json:"name"`
+
+	// Description
+	Description *string `json:"description,omitempty"`
+
+	// Currency
+	Currency currency.Code `json:"currency"`
+
+	// InstanceType
+	InstanceType AddonInstanceType `json:"instanceType"`
+
+	// Metadata
+	Metadata models.Metadata `json:"metadata,omitempty"`
+
+	// Annotations
+	Annotations models.Annotations `json:"annotations,omitempty"`
+}
+
+func (m AddonMeta) Validate() error {
+	var errs []error
+
+	if err := m.EffectivePeriod.Validate(); err != nil {
+		errs = append(errs, fmt.Errorf("invalid effective period: %w", err))
+	}
+
+	if m.Key == "" {
+		errs = append(errs, ErrAddonKeyEmpty)
+	}
+
+	if m.Name == "" {
+		errs = append(errs, ErrAddonNameEmpty)
+	}
+
+	if err := m.Currency.Validate(); err != nil {
+		errs = append(errs, ErrCurrencyInvalid)
+	}
+
+	if err := m.InstanceType.Validate(); err != nil {
+		errs = append(errs, err)
+	}
+
+	return models.NewNillableGenericValidationError(errors.Join(errs...))
+}
+
+func (m AddonMeta) Equal(v AddonMeta) bool {
+	if m.Key != v.Key {
+		return false
+	}
+
+	if m.Version != v.Version {
+		return false
+	}
+
+	if m.Name != v.Name {
+		return false
+	}
+
+	if lo.FromPtr(m.Description) != lo.FromPtr(v.Description) {
+		return false
+	}
+
+	if m.Currency != v.Currency {
+		return false
+	}
+
+	if m.InstanceType != v.InstanceType {
+		return false
+	}
+
+	if !m.EffectivePeriod.Equal(v.EffectivePeriod) {
+		return false
+	}
+
+	if !m.Metadata.Equal(v.Metadata) {
+		return false
+	}
+
+	if !maps.Equal(m.Annotations, v.Annotations) {
+		return false
+	}
+
+	return true
+}
+
+// Status returns the current status of the Addons
+func (m AddonMeta) Status() AddonStatus {
+	return m.StatusAt(clock.Now())
+}
+
+// StatusAt returns the Addon status relative to time t.
+func (m AddonMeta) StatusAt(t time.Time) AddonStatus {
+	from := lo.FromPtr(m.EffectiveFrom)
+	to := lo.FromPtr(m.EffectiveTo)
+
+	// Add-on has DraftStatus if neither the EffectiveFrom nor EffectiveTo are set
+	if from.IsZero() && to.IsZero() {
+		return AddonStatusDraft
+	}
+
+	// Add-on has ArchivedStatus if EffectiveTo is in the past relative to time t.
+	if from.Before(t) && (to.Before(t) && from.Before(to)) {
+		return AddonStatusArchived
+	}
+
+	// Add-on has ActiveStatus if EffectiveFrom is set in the past relative to time t and EffectiveTo is not set
+	// or in the future relative to time t.
+	if from.Before(t) && (to.IsZero() || to.After(t)) {
+		return AddonStatusActive
+	}
+
+	return AddonStatusInvalid
+}
+
+var (
+	_ models.Validator              = (*Addon)(nil)
+	_ models.CustomValidator[Addon] = (*Addon)(nil)
+	_ models.Equaler[Addon]         = (*Addon)(nil)
+)
+
+type Addon struct {
+	AddonMeta
+
+	// RateCards
+	RateCards RateCards `json:"rateCards"`
+}
+
+func (a Addon) ValidateWith(validators ...models.ValidatorFunc[Addon]) error {
+	return models.Validate(a, validators...)
+}
+
+func (a Addon) HasUnitConfig() bool {
+	return a.RateCards.HasUnitConfig()
+}
+
+// ValidationErrors returns a list of possible validation errors for the add-on.
+// It returns nil if the add-on has no validation issues.
+func (a Addon) ValidationErrors() (models.ValidationIssues, error) {
+	return models.AsValidationIssues(a.Validate())
+}
+
+func (a Addon) Validate() error {
+	return a.ValidateWith(
+		ValidateAddonMeta(),
+		ValidateAddonRateCards(),
+	)
+}
+
+// Publishable validates the Addon to ensure that it meets all requirements needed for being published.
+// It is a stricter version of Validate. It is the caller's responsibility to handle managed resource-specific parameters
+// to ensure the Addon is eligible for publishing. E.g. checking the DeletedAt attribute of the addon.Addon.
+func (a Addon) Publishable() error {
+	return a.ValidateWith(
+		ValidateAddonMeta(),
+		ValidateAddonRateCards(),
+		ValidateAddonStatusPublishable(),
+		ValidateAddonHasSingleBillingCadence(),
+		ValidateAddonHasCompatiblePrices(),
+	)
+}
+
+func (a Addon) Equal(v Addon) bool {
+	if !a.AddonMeta.Equal(v.AddonMeta) {
+		return false
+	}
+
+	return a.RateCards.Equal(v.RateCards)
+}
+
+type AddonInstanceType string
+
+const (
+	AddonInstanceTypeSingle   AddonInstanceType = "single"
+	AddonInstanceTypeMultiple AddonInstanceType = "multiple"
+)
+
+func (a AddonInstanceType) Validate() error {
+	switch a {
+	case AddonInstanceTypeSingle, AddonInstanceTypeMultiple:
+		return nil
+	default:
+		return ErrAddonInvalidInstanceType
+	}
+}
+
+func (a AddonInstanceType) Values() []string {
+	return []string{
+		string(AddonInstanceTypeSingle),
+		string(AddonInstanceTypeMultiple),
+	}
+}
+
+// ValidateAddonMeta returns a validation function can be passed to the object
+// which implements models.CustomValidator interface. It validates attributes in AddonMeta of Addon.
+func ValidateAddonMeta() models.ValidatorFunc[Addon] {
+	return func(a Addon) error {
+		return a.AddonMeta.Validate()
+	}
+}
+
+// ValidateAddonRateCards returns a validation function can be passed to the object
+// which implements models.CustomValidator interface. It checks for invalid and duplicated ratecards.
+func ValidateAddonRateCards() models.ValidatorFunc[Addon] {
+	return func(a Addon) error {
+		if len(a.RateCards) == 0 {
+			return ErrAddonHasNoRateCards
+		}
+
+		return ValidateRateCards()(a.RateCards)
+	}
+}
+
+func ValidateAddonStatusPublishable() models.ValidatorFunc[Addon] {
+	return func(a Addon) error {
+		if err := ValidateAddonWithStatus(AddonStatusDraft)(a); err != nil {
+			return ErrAddonInvalidStatusForPublish
+		}
+
+		return nil
+	}
+}
+
+func ValidateAddonWithStatus(allowed ...AddonStatus) models.ValidatorFunc[Addon] {
+	return func(a Addon) error {
+		status := a.Status()
+		if lo.Contains(allowed, status) {
+			return nil
+		}
+
+		return ErrAddonInvalidStatus
+	}
+}
+
+func ValidateAddonHasSingleBillingCadence() models.ValidatorFunc[Addon] {
+	return func(a Addon) error {
+		if a.RateCards.SingleBillingCadence() {
+			return nil
+		}
+
+		return models.ErrorWithFieldPrefix(
+			models.NewFieldSelectorGroup(models.NewFieldSelector("ratecards").WithExpression(models.WildCard)),
+			ErrRateCardMultipleBillingCadence,
+		)
+	}
+}
+
+func ValidateAddonHasCompatiblePrices() models.ValidatorFunc[Addon] {
+	return func(a Addon) error {
+		switch a.InstanceType {
+		case AddonInstanceTypeSingle:
+			return nil
+		case AddonInstanceTypeMultiple:
+			for _, rc := range a.RateCards {
+				if price := rc.AsMeta().Price; price != nil && price.Type() != FlatPriceType {
+					return models.ErrorWithFieldPrefix(
+						models.NewFieldSelectorGroup(models.NewFieldSelector("ratecards").
+							WithExpression(models.NewFieldAttrValue("key", rc.Key()))),
+						ErrAddonInvalidPriceForMultiInstance,
+					)
+				}
+			}
+
+			return nil
+		default:
+			return ErrAddonInvalidInstanceType
+		}
+	}
+}
+
+// Determines if an Addon RateCard will effect a given Plan RateCard
+// Right now we only support a single RateCard per addon effecting a single plan RateCard and we match them by key.
+// FIXME(galexi): matching like this is unwieldy as sometimes we'd want to match productcatalog.RateCard, sometimes addon.RateCard, or subscriptionaddon.RateCard...
+func AddonRateCardMatcherForAGivenPlanRateCard(planRateCard RateCard) func(addonRateCard RateCard) bool {
+	return func(addonRateCard RateCard) bool {
+		return addonRateCard.Key() == planRateCard.Key()
+	}
+}
+
+func ValidateAddonWithFeatures(ctx context.Context, resolver NamespacedFeatureResolver) models.ValidatorFunc[Addon] {
+	return func(a Addon) error {
+		return ValidateRateCardsWithFeatures(ctx, resolver)(a.RateCards)
+	}
+}

openmeter/productcatalog/addon/adapter/adapter.go

@@ -0,0 +1,83 @@
+package adapter
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+	"log/slog"
+
+	entdb "github.com/openmeterio/openmeter/openmeter/ent/db"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/addon"
+	"github.com/openmeterio/openmeter/pkg/framework/entutils"
+	"github.com/openmeterio/openmeter/pkg/framework/transaction"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+var _ models.Validator = (*Config)(nil)
+
+type Config struct {
+	Client *entdb.Client
+	Logger *slog.Logger
+}
+
+func (c Config) Validate() error {
+	var errs []error
+
+	if c.Client == nil {
+		errs = append(errs, errors.New("postgres client is required"))
+	}
+
+	if c.Logger == nil {
+		errs = append(errs, errors.New("logger is required"))
+	}
+
+	if len(errs) > 0 {
+		return errors.Join(errs...)
+	}
+
+	return nil
+}
+
+func New(config Config) (addon.Repository, error) {
+	if err := config.Validate(); err != nil {
+		return nil, err
+	}
+
+	return &adapter{
+		db:     config.Client,
+		logger: config.Logger,
+	}, nil
+}
+
+var _ addon.Repository = (*adapter)(nil)
+
+type adapter struct {
+	db *entdb.Client
+
+	logger *slog.Logger
+}
+
+func (a *adapter) Tx(ctx context.Context) (context.Context, transaction.Driver, error) {
+	ctx, rawConfig, eDriver, err := a.db.HijackTx(ctx, &sql.TxOptions{
+		ReadOnly: false,
+	})
+	if err != nil {
+		return nil, nil, fmt.Errorf("failed to hijack transaction: %w", err)
+	}
+
+	return ctx, entutils.NewTxDriver(eDriver, rawConfig), nil
+}
+
+func (a *adapter) WithTx(ctx context.Context, tx *entutils.TxDriver) *adapter {
+	txClient := entdb.NewTxClientFromRawConfig(ctx, *tx.GetConfig())
+
+	return &adapter{
+		db:     txClient.Client(),
+		logger: a.logger,
+	}
+}
+
+func (a *adapter) Self() *adapter {
+	return a
+}

openmeter/productcatalog/addon/adapter/adapter_test.go

@@ -0,0 +1,548 @@
+package adapter_test
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	decimal "github.com/alpacahq/alpacadecimal"
+	"github.com/samber/lo"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	entdb "github.com/openmeterio/openmeter/openmeter/ent/db"
+	"github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/addon"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/addon/adapter"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	pctestutils "github.com/openmeterio/openmeter/openmeter/productcatalog/testutils"
+	"github.com/openmeterio/openmeter/openmeter/testutils"
+	"github.com/openmeterio/openmeter/pkg/clock"
+	"github.com/openmeterio/openmeter/pkg/datetime"
+	"github.com/openmeterio/openmeter/pkg/filter"
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+)
+
+var MonthPeriod = datetime.ISODurationFromDuration(30 * 24 * time.Hour)
+
+func TestPostgresAdapter(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	env := pctestutils.NewTestEnv(t)
+	t.Cleanup(func() {
+		env.Close(t)
+	})
+
+	t.Run("Addon", func(t *testing.T) {
+		t.Run("Create", func(t *testing.T) {
+			// Get new namespace ID
+			namespace := pctestutils.NewTestNamespace(t)
+
+			// Setup meter repository
+			err := env.Meter.ReplaceMeters(ctx, pctestutils.NewTestMeters(t, namespace))
+			require.NoError(t, err, "replacing meters must not fail")
+
+			result, err := env.Meter.ListMeters(ctx, meter.ListMetersParams{
+				Page: pagination.Page{
+					PageSize:   1000,
+					PageNumber: 1,
+				},
+				Namespace: namespace,
+			})
+			require.NoErrorf(t, err, "listing meters must not fail")
+
+			meters := result.Items
+			require.NotEmptyf(t, meters, "list of Meters must not be empty")
+
+			// Set a feature for each meter
+			features := make([]feature.Feature, 0, len(meters))
+			for _, m := range meters {
+				input := pctestutils.NewTestFeatureFromMeter(t, &m)
+
+				feat, err := env.Feature.CreateFeature(ctx, input)
+				require.NoErrorf(t, err, "creating feature must not fail")
+				require.NotNil(t, feat, "feature must not be empty")
+
+				features = append(features, feat)
+			}
+
+			addonV1Input := pctestutils.NewTestAddon(t, namespace, productcatalog.RateCards{
+				&productcatalog.UsageBasedRateCard{
+					RateCardMeta: productcatalog.RateCardMeta{
+						Key:                 features[0].Key,
+						Name:                features[0].Name,
+						Description:         lo.ToPtr(features[0].Name),
+						Metadata:            models.Metadata{"name": features[0].Name},
+						FeatureKey:          lo.ToPtr(features[0].Key),
+						FeatureID:           lo.ToPtr(features[0].ID),
+						EntitlementTemplate: productcatalog.NewEntitlementTemplateFrom(productcatalog.BooleanEntitlementTemplate{}),
+						TaxConfig: &productcatalog.TaxConfig{
+							Stripe: &productcatalog.StripeTaxConfig{
+								Code: "txcd_10000000",
+							},
+						},
+						Price: productcatalog.NewPriceFrom(productcatalog.TieredPrice{
+							Mode: productcatalog.VolumeTieredPrice,
+							Tiers: []productcatalog.PriceTier{
+								{
+									UpToAmount: lo.ToPtr(decimal.NewFromInt(1000)),
+									FlatPrice: &productcatalog.PriceTierFlatPrice{
+										Amount: decimal.NewFromInt(100),
+									},
+									UnitPrice: &productcatalog.PriceTierUnitPrice{
+										Amount: decimal.NewFromInt(50),
+									},
+								},
+								{
+									UpToAmount: nil,
+									FlatPrice: &productcatalog.PriceTierFlatPrice{
+										Amount: decimal.NewFromInt(5),
+									},
+									UnitPrice: &productcatalog.PriceTierUnitPrice{
+										Amount: decimal.NewFromInt(25),
+									},
+								},
+							},
+							Commitments: productcatalog.Commitments{
+								MinimumAmount: lo.ToPtr(decimal.NewFromInt(1000)),
+								MaximumAmount: nil,
+							},
+						}),
+						UnitConfig: &productcatalog.UnitConfig{
+							Operation:        productcatalog.UnitConfigOperationDivide,
+							ConversionFactor: decimal.NewFromInt(1000),
+							Rounding:         productcatalog.UnitConfigRoundingModeCeiling,
+							Precision:        0,
+							DisplayUnit:      lo.ToPtr("K"),
+						},
+					},
+					BillingCadence: MonthPeriod,
+				},
+			}...)
+
+			var addonV1 *addon.Addon
+
+			addonV1, err = env.AddonRepository.CreateAddon(ctx, addonV1Input)
+			require.NoErrorf(t, err, "creating new add-on must not fail")
+
+			require.NotNilf(t, addonV1, "add-on must not be nil")
+
+			addon.AssertAddonCreateInputEqual(t, addonV1Input, *addonV1)
+
+			t.Run("Get", func(t *testing.T) {
+				t.Run("ById", func(t *testing.T) {
+					getAddonV1, err := env.AddonRepository.GetAddon(ctx, addon.GetAddonInput{
+						NamespacedID: models.NamespacedID{
+							Namespace: namespace,
+							ID:        addonV1.ID,
+						},
+					})
+					assert.NoErrorf(t, err, "getting add-on by id must not fail")
+
+					require.NotNilf(t, getAddonV1, "add-on must not be nil")
+
+					addon.AssertAddonEqual(t, *addonV1, *getAddonV1)
+				})
+
+				t.Run("ByKey", func(t *testing.T) {
+					getAddonV1, err := env.AddonRepository.GetAddon(ctx, addon.GetAddonInput{
+						NamespacedID: models.NamespacedID{
+							Namespace: namespace,
+						},
+						Key:           addonV1Input.Key,
+						IncludeLatest: true,
+					})
+					assert.NoErrorf(t, err, "getting add-on by key must not fail")
+
+					require.NotNilf(t, getAddonV1, "add-on must not be nil")
+
+					addon.AssertAddonEqual(t, *addonV1, *getAddonV1)
+				})
+
+				t.Run("ByKeyVersion", func(t *testing.T) {
+					getAddonV1, err := env.AddonRepository.GetAddon(ctx, addon.GetAddonInput{
+						NamespacedID: models.NamespacedID{
+							Namespace: namespace,
+						},
+						Key:     addonV1Input.Key,
+						Version: 1,
+					})
+					assert.NoErrorf(t, err, "getting plan by key and version must not fail")
+
+					require.NotNilf(t, getAddonV1, "plan must not be nil")
+
+					addon.AssertAddonEqual(t, *addonV1, *getAddonV1)
+				})
+			})
+
+			t.Run("List", func(t *testing.T) {
+				t.Run("ByIdFilter", func(t *testing.T) {
+					listAddonV1, err := env.AddonRepository.ListAddons(ctx, addon.ListAddonsInput{
+						Namespaces: []string{namespace},
+						ID: &filter.FilterULID{
+							FilterString: filter.FilterString{
+								Eq: &addonV1.ID,
+							},
+						},
+					})
+					assert.NoErrorf(t, err, "listing add-on by id filter must not fail")
+
+					require.Lenf(t, listAddonV1.Items, 1, "add-ons must not be empty")
+
+					addon.AssertAddonEqual(t, *addonV1, listAddonV1.Items[0])
+				})
+
+				t.Run("ByKeyFilter", func(t *testing.T) {
+					listAddonV1, err := env.AddonRepository.ListAddons(ctx, addon.ListAddonsInput{
+						Namespaces: []string{namespace},
+						Key: &filter.FilterString{
+							Eq: &addonV1Input.Key,
+						},
+					})
+					assert.NoErrorf(t, err, "getting add-on by key filter must not fail")
+
+					require.Lenf(t, listAddonV1.Items, 1, "add-ons must not be empty")
+
+					addon.AssertAddonEqual(t, *addonV1, listAddonV1.Items[0])
+				})
+
+				t.Run("ByNameFilter", func(t *testing.T) {
+					listAddonV1, err := env.AddonRepository.ListAddons(ctx, addon.ListAddonsInput{
+						Namespaces: []string{namespace},
+						Name: &filter.FilterString{
+							Eq: &addonV1Input.Name,
+						},
+					})
+					assert.NoErrorf(t, err, "getting add-on by name filter must not fail")
+
+					require.Lenf(t, listAddonV1.Items, 1, "add-ons must not be empty")
+
+					addon.AssertAddonEqual(t, *addonV1, listAddonV1.Items[0])
+				})
+
+				t.Run("ByCurrencyFilter", func(t *testing.T) {
+					currencyStr := string(addonV1Input.Currency)
+					listAddonV1, err := env.AddonRepository.ListAddons(ctx, addon.ListAddonsInput{
+						Namespaces: []string{namespace},
+						Currency: &filter.FilterString{
+							Eq: &currencyStr,
+						},
+					})
+					assert.NoErrorf(t, err, "getting add-on by currency filter must not fail")
+
+					require.NotEmpty(t, listAddonV1.Items, "add-ons must not be empty")
+				})
+
+				t.Run("ByKeyVersion", func(t *testing.T) {
+					listAddonV1, err := env.AddonRepository.ListAddons(ctx, addon.ListAddonsInput{
+						Namespaces:  []string{namespace},
+						KeyVersions: map[string][]int{addonV1Input.Key: {1}},
+					})
+					assert.NoErrorf(t, err, "getting add-on by key and version must not fail")
+
+					require.Lenf(t, listAddonV1.Items, 1, "add-ons must not be empty")
+
+					addon.AssertAddonEqual(t, *addonV1, listAddonV1.Items[0])
+				})
+			})
+
+			t.Run("Update", func(t *testing.T) {
+				now := time.Now()
+
+				addonV1Update := addon.UpdateAddonInput{
+					NamespacedID: models.NamespacedID{
+						Namespace: namespace,
+						ID:        addonV1.ID,
+					},
+					EffectivePeriod: productcatalog.EffectivePeriod{
+						EffectiveFrom: lo.ToPtr(now.UTC()),
+						EffectiveTo:   lo.ToPtr(now.Add(30 * 24 * time.Hour).UTC()),
+					},
+					Name:        lo.ToPtr("Addon v1 Published"),
+					Description: lo.ToPtr("Addon v1 Published"),
+					Metadata: &models.Metadata{
+						"name":        "Addon v1 Published",
+						"description": "Addon v1 Published",
+					},
+					RateCards: &productcatalog.RateCards{
+						&productcatalog.FlatFeeRateCard{
+							RateCardMeta: productcatalog.RateCardMeta{
+								Key:                 "ratecard-2",
+								Name:                "RateCard 2",
+								Description:         lo.ToPtr("RateCard 2"),
+								Metadata:            models.Metadata{"name": "ratecard-2"},
+								FeatureKey:          nil,
+								FeatureID:           nil,
+								EntitlementTemplate: nil,
+								TaxConfig: &productcatalog.TaxConfig{
+									Stripe: &productcatalog.StripeTaxConfig{
+										Code: "txcd_10000000",
+									},
+								},
+								Price: productcatalog.NewPriceFrom(productcatalog.FlatPrice{
+									Amount:      decimal.NewFromInt(0),
+									PaymentTerm: productcatalog.InArrearsPaymentTerm,
+								}),
+							},
+							BillingCadence: &MonthPeriod,
+						},
+					},
+				}
+
+				addonV1, err = env.AddonRepository.UpdateAddon(ctx, addonV1Update)
+				require.NoErrorf(t, err, "updating add-on must not fail")
+
+				require.NotNilf(t, addonV1, "add-on must not be nil")
+
+				addon.AssertAddonUpdateInputEqual(t, addonV1Update, *addonV1)
+			})
+
+			t.Run("Delete", func(t *testing.T) {
+				err = env.AddonRepository.DeleteAddon(ctx, addon.DeleteAddonInput{
+					NamespacedID: models.NamespacedID{
+						Namespace: addonV1.Namespace,
+						ID:        addonV1.ID,
+					},
+				})
+				require.NoErrorf(t, err, "deleting ad-on must not fail")
+
+				getAddonV1, err := env.AddonRepository.GetAddon(ctx, addon.GetAddonInput{
+					NamespacedID: models.NamespacedID{
+						Namespace: namespace,
+						ID:        addonV1.ID,
+					},
+				})
+				require.NoErrorf(t, err, "getting add-on by id must not fail")
+
+				require.NotNilf(t, getAddonV1, "add-on must not be nil")
+
+				addon.AssertAddonEqual(t, *addonV1, *getAddonV1)
+			})
+		})
+
+		t.Run("ListAddonStatusFilter", func(t *testing.T) {
+			// Get new namespace ID
+			namespace := pctestutils.NewTestNamespace(t)
+
+			addonV1Input := pctestutils.NewTestAddon(t, namespace, productcatalog.RateCards{
+				&productcatalog.FlatFeeRateCard{
+					RateCardMeta: productcatalog.RateCardMeta{
+						Key:  "ratecard",
+						Name: "ratecard",
+					},
+				},
+			}...)
+
+			inputs := []struct {
+				Version         int
+				EffectivePeriod productcatalog.EffectivePeriod
+			}{
+				{
+					Version: 1,
+					EffectivePeriod: productcatalog.EffectivePeriod{
+						EffectiveFrom: lo.ToPtr(testutils.GetRFC3339Time(t, "2025-03-15T00:00:00Z")),
+						EffectiveTo:   lo.ToPtr(testutils.GetRFC3339Time(t, "2025-03-15T12:00:00Z")),
+					},
+				},
+				{
+					Version: 2,
+					EffectivePeriod: productcatalog.EffectivePeriod{
+						EffectiveFrom: lo.ToPtr(testutils.GetRFC3339Time(t, "2025-03-15T12:00:00Z")),
+					},
+				},
+				{
+					Version:         3,
+					EffectivePeriod: productcatalog.EffectivePeriod{},
+				},
+			}
+
+			for _, in := range inputs {
+				addonV1Input.Addon.AddonMeta.Version = in.Version
+
+				addonVersion, err := env.AddonRepository.CreateAddon(ctx, addonV1Input)
+				require.NoErrorf(t, err, "creating new add-on must not fail")
+
+				_, err = env.AddonRepository.UpdateAddon(ctx, addon.UpdateAddonInput{
+					NamespacedID: models.NamespacedID{
+						Namespace: namespace,
+						ID:        addonVersion.ID,
+					},
+					EffectivePeriod: in.EffectivePeriod,
+				})
+				require.NoErrorf(t, err, "updating new add-on must not fail")
+			}
+
+			tests := []struct {
+				name          string
+				at            time.Time
+				filter        []productcatalog.AddonStatus
+				expectVersion []int
+			}{
+				{
+					name: "Active",
+					at:   testutils.GetRFC3339Time(t, "2025-03-16T00:00:00Z"),
+					filter: []productcatalog.AddonStatus{
+						productcatalog.AddonStatusActive,
+					},
+					expectVersion: []int{2},
+				},
+				{
+					name: "Draft",
+					at:   testutils.GetRFC3339Time(t, "2025-03-16T00:00:00Z"),
+					filter: []productcatalog.AddonStatus{
+						productcatalog.AddonStatusDraft,
+					},
+					expectVersion: []int{3},
+				},
+				{
+					name: "Archived",
+					at:   testutils.GetRFC3339Time(t, "2025-03-16T00:00:00Z"),
+					filter: []productcatalog.AddonStatus{
+						productcatalog.AddonStatusArchived,
+					},
+					expectVersion: []int{1},
+				},
+				{
+					name: "All",
+					at:   testutils.GetRFC3339Time(t, "2025-03-16T00:00:00Z"),
+					filter: []productcatalog.AddonStatus{
+						productcatalog.AddonStatusActive,
+						productcatalog.AddonStatusDraft,
+						productcatalog.AddonStatusArchived,
+					},
+					expectVersion: []int{1, 2, 3},
+				},
+				{
+					name: "Scheduled",
+					at:   testutils.GetRFC3339Time(t, "2025-03-15T01:00:00Z"),
+					filter: []productcatalog.AddonStatus{
+						productcatalog.AddonStatusInvalid,
+					},
+					expectVersion: []int{},
+				},
+			}
+
+			defer clock.ResetTime()
+
+			for _, test := range tests {
+				t.Run(test.name, func(t *testing.T) {
+					clock.SetTime(test.at)
+
+					list, err := env.AddonRepository.ListAddons(ctx, addon.ListAddonsInput{
+						Namespaces: []string{namespace},
+						Status:     test.filter,
+					})
+					require.NoError(t, err, "listing add-ons must not fail")
+
+					versions := lo.Map(list.Items, func(item addon.Addon, _ int) int {
+						return item.Version
+					})
+
+					require.ElementsMatch(t, test.expectVersion, versions)
+				})
+			}
+		})
+	})
+}
+
+func TestListAddonsExcludeUnitConfig(t *testing.T) {
+	ctx := context.Background()
+
+	env := pctestutils.NewTestEnv(t)
+	t.Cleanup(func() { env.Close(t) })
+
+	namespace := pctestutils.NewTestNamespace(t)
+
+	require.NoError(t, env.Meter.ReplaceMeters(ctx, pctestutils.NewTestMeters(t, namespace)),
+		"replacing meters must not fail")
+	meters, err := env.Meter.ListMeters(ctx, meter.ListMetersParams{
+		Page:      pagination.Page{PageSize: 1000, PageNumber: 1},
+		Namespace: namespace,
+	})
+	require.NoError(t, err, "listing meters must not fail")
+	require.NotEmpty(t, meters.Items, "list of meters must not be empty")
+
+	feat, err := env.Feature.CreateFeature(ctx, pctestutils.NewTestFeatureFromMeter(t, &meters.Items[0]))
+	require.NoError(t, err, "creating feature must not fail")
+
+	// Plain add-on: flat rate card, no unit_config → v1-representable.
+	plainInput := pctestutils.NewTestAddon(t, namespace, &productcatalog.FlatFeeRateCard{
+		RateCardMeta: productcatalog.RateCardMeta{Key: "flat", Name: "Flat"},
+	})
+	plainInput.Addon.Key = "plain"
+	_, err = env.AddonRepository.CreateAddon(ctx, plainInput)
+	require.NoError(t, err, "creating plain add-on must not fail")
+
+	// unit_config add-on: usage-based rate card carrying a unit_config → not v1-representable.
+	ucInput := pctestutils.NewTestAddon(t, namespace, &productcatalog.UsageBasedRateCard{
+		RateCardMeta: productcatalog.RateCardMeta{
+			Key:        feat.Key,
+			Name:       "UC RateCard",
+			FeatureKey: lo.ToPtr(feat.Key),
+			FeatureID:  lo.ToPtr(feat.ID),
+			Price:      productcatalog.NewPriceFrom(productcatalog.UnitPrice{Amount: decimal.NewFromInt(1)}),
+			UnitConfig: &productcatalog.UnitConfig{
+				Operation:        productcatalog.UnitConfigOperationDivide,
+				ConversionFactor: decimal.NewFromInt(1000),
+			},
+		},
+		BillingCadence: MonthPeriod,
+	})
+	ucInput.Addon.Key = "with-uc"
+	_, err = env.AddonRepository.CreateAddon(ctx, ucInput)
+	require.NoError(t, err, "creating unit_config add-on must not fail")
+
+	t.Run("included when ExcludeUnitConfig is false", func(t *testing.T) {
+		list, err := env.AddonRepository.ListAddons(ctx, addon.ListAddonsInput{
+			Namespaces: []string{namespace},
+		})
+		require.NoError(t, err, "listing add-ons must not fail")
+
+		keys := lo.Map(list.Items, func(a addon.Addon, _ int) string { return a.Key })
+		require.ElementsMatch(t, []string{"plain", "with-uc"}, keys)
+		require.Equal(t, 2, list.TotalCount, "TotalCount must count both add-ons")
+	})
+
+	t.Run("excluded when ExcludeUnitConfig is true, TotalCount stays consistent", func(t *testing.T) {
+		list, err := env.AddonRepository.ListAddons(ctx, addon.ListAddonsInput{
+			Namespaces:        []string{namespace},
+			ExcludeUnitConfig: true,
+		})
+		require.NoError(t, err, "listing add-ons must not fail")
+
+		keys := lo.Map(list.Items, func(a addon.Addon, _ int) string { return a.Key })
+		require.ElementsMatch(t, []string{"plain"}, keys)
+		require.Equal(t, 1, list.TotalCount, "TotalCount must exclude the unit_config add-on, not just the page slice")
+	})
+}
+
+// TestFromPlanRateCardRowMapsUnitConfig guards the cross-package mapper used when an
+// add-on is loaded with expanded linked plans
+// (FromAddonRow → FromPlanAddonRow → FromPlanRow → FromPlanPhaseRow → FromPlanRateCardRow).
+// This mapper is separate from the own-type add-on rate-card mapper, so a RateCardMeta field
+// added to one is not automatically carried by the other; UnitConfig dropping here would
+// surface a stored config as nil and rate raw usage instead of converted units.
+func TestFromPlanRateCardRowMapsUnitConfig(t *testing.T) {
+	unitConfig := &productcatalog.UnitConfig{
+		Operation:        productcatalog.UnitConfigOperationDivide,
+		ConversionFactor: decimal.NewFromInt(1000),
+		Rounding:         productcatalog.UnitConfigRoundingModeCeiling,
+		Precision:        0,
+		DisplayUnit:      lo.ToPtr("K"),
+	}
+
+	rc, err := adapter.FromPlanRateCardRow(entdb.PlanRateCard{
+		Key:        "rc",
+		Name:       "RC",
+		Type:       productcatalog.UsageBasedRateCardType,
+		Price:      productcatalog.NewPriceFrom(productcatalog.UnitPrice{Amount: decimal.NewFromInt(1)}),
+		UnitConfig: unitConfig,
+	})
+	require.NoError(t, err, "mapping plan rate card row must not fail")
+
+	require.Equal(t, unitConfig, rc.AsMeta().UnitConfig,
+		"UnitConfig must survive the add-on adapter's linked plan mapper")
+}

openmeter/productcatalog/addon/adapter/addon.go

@@ -0,0 +1,572 @@
+package adapter
+
+import (
+	"context"
+	"fmt"
+	"slices"
+	"time"
+
+	"entgo.io/ent/dialect/sql"
+
+	entdb "github.com/openmeterio/openmeter/openmeter/ent/db"
+	addondb "github.com/openmeterio/openmeter/openmeter/ent/db/addon"
+	addonratecarddb "github.com/openmeterio/openmeter/openmeter/ent/db/addonratecard"
+	planaddondb "github.com/openmeterio/openmeter/openmeter/ent/db/planaddon"
+	phasedb "github.com/openmeterio/openmeter/openmeter/ent/db/planphase"
+	ratecarddb "github.com/openmeterio/openmeter/openmeter/ent/db/planratecard"
+	"github.com/openmeterio/openmeter/openmeter/ent/db/predicate"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/addon"
+	"github.com/openmeterio/openmeter/pkg/clock"
+	"github.com/openmeterio/openmeter/pkg/filter"
+	"github.com/openmeterio/openmeter/pkg/framework/entutils"
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+	"github.com/openmeterio/openmeter/pkg/sortx"
+)
+
+func (a *adapter) ListAddons(ctx context.Context, params addon.ListAddonsInput) (pagination.Result[addon.Addon], error) {
+	fn := func(ctx context.Context, a *adapter) (pagination.Result[addon.Addon], error) {
+		if err := params.Validate(); err != nil {
+			return pagination.Result[addon.Addon]{}, fmt.Errorf("invalid list add-on parameters: %w", err)
+		}
+
+		query := a.db.Addon.Query()
+
+		if len(params.Namespaces) > 0 {
+			query = query.Where(addondb.NamespaceIn(params.Namespaces...))
+		}
+
+		if len(params.KeyVersions) > 0 {
+			var kvFilters []predicate.Addon
+			for key, version := range params.KeyVersions {
+				kvFilters = append(kvFilters, addondb.And(addondb.Key(key), addondb.VersionIn(version...)))
+			}
+			query = query.Where(addondb.Or(kvFilters...))
+		}
+
+		query = filter.ApplyToQuery(query, params.ID, addondb.FieldID)
+		query = filter.ApplyToQuery(query, params.Key, addondb.FieldKey)
+		query = filter.ApplyToQuery(query, params.Name, addondb.FieldName)
+		query = filter.ApplyToQuery(query, params.Currency, addondb.FieldCurrency)
+
+		if params.ExcludeUnitConfig {
+			query = query.Where(addondb.Not(addondb.HasRatecardsWith(
+				addonratecarddb.UnitConfigNotNil(),
+				addonratecarddb.DeletedAtIsNil(),
+			)))
+		}
+
+		if !params.IncludeDeleted {
+			query = query.Where(addondb.DeletedAtIsNil())
+		}
+
+		if len(params.Status) > 0 {
+			var predicates []predicate.Addon
+
+			now := clock.Now().UTC()
+
+			if slices.Contains(params.Status, productcatalog.AddonStatusActive) {
+				predicates = append(predicates, addondb.And(
+					addondb.EffectiveFromLTE(now),
+					addondb.Or(
+						addondb.EffectiveToGTE(now),
+						addondb.EffectiveToIsNil(),
+					),
+				))
+			}
+
+			if slices.Contains(params.Status, productcatalog.AddonStatusDraft) {
+				predicates = append(predicates, addondb.And(
+					addondb.EffectiveFromIsNil(),
+					addondb.EffectiveToIsNil(),
+				))
+			}
+
+			if slices.Contains(params.Status, productcatalog.AddonStatusArchived) {
+				predicates = append(predicates, addondb.EffectiveToLT(now))
+			}
+
+			if slices.Contains(params.Status, productcatalog.AddonStatusInvalid) {
+				predicates = append(predicates, func(s *sql.Selector) {
+					s.Where(sql.ColumnsLT(addondb.FieldEffectiveTo, addondb.FieldEffectiveFrom))
+				})
+			}
+
+			if len(predicates) > 0 {
+				query = query.Where(addondb.Or(predicates...))
+			}
+		}
+
+		// Eager load ratecards
+		query = query.WithRatecards(
+			AddonEagerLoadRateCardsFn,
+		)
+
+		order := entutils.GetOrdering(sortx.OrderDefault)
+		if !params.Order.IsDefaultValue() {
+			order = entutils.GetOrdering(params.Order)
+		}
+
+		switch params.OrderBy {
+		case addon.OrderByCreatedAt:
+			query = query.Order(addondb.ByCreatedAt(order...))
+		case addon.OrderByUpdatedAt:
+			query = query.Order(addondb.ByUpdatedAt(order...))
+		case addon.OrderByVersion:
+			query = query.Order(addondb.ByVersion(order...))
+		case addon.OrderByKey:
+			query = query.Order(addondb.ByKey(order...))
+		case addon.OrderByName:
+			query = query.Order(addondb.ByName(order...))
+		case addon.OrderByID:
+			fallthrough
+		default:
+			query = query.Order(addondb.ByID(order...))
+		}
+
+		response := pagination.Result[addon.Addon]{
+			Page: params.Page,
+		}
+
+		paged, err := query.Paginate(ctx, params.Page)
+		if err != nil {
+			return response, fmt.Errorf("failed to list add-ons: %w", err)
+		}
+
+		result := make([]addon.Addon, 0, len(paged.Items))
+		for _, item := range paged.Items {
+			if item == nil {
+				a.logger.WarnContext(ctx, "invalid query result: nil add-on received")
+				continue
+			}
+
+			p, err := FromAddonRow(*item)
+			if err != nil {
+				return response, fmt.Errorf("failed to cast add-on: %w", err)
+			}
+
+			result = append(result, *p)
+		}
+
+		response.TotalCount = paged.TotalCount
+		response.Items = result
+
+		return response, nil
+	}
+
+	return entutils.TransactingRepo[pagination.Result[addon.Addon], *adapter](ctx, a, fn)
+}
+
+func (a *adapter) CreateAddon(ctx context.Context, params addon.CreateAddonInput) (*addon.Addon, error) {
+	fn := func(ctx context.Context, a *adapter) (*addon.Addon, error) {
+		if err := params.Validate(); err != nil {
+			return nil, fmt.Errorf("invalid create add-on parameters: %w", err)
+		}
+
+		if params.Version == 0 {
+			params.Version = 1
+		}
+
+		addonRow, err := a.db.Addon.Create().
+			SetKey(params.Key).
+			SetNamespace(params.Namespace).
+			SetName(params.Name).
+			SetNillableDescription(params.Description).
+			SetCurrency(params.Currency.String()).
+			SetMetadata(params.Metadata).
+			SetVersion(params.Version).
+			SetAnnotations(params.Annotations).
+			SetInstanceType(params.InstanceType).
+			Save(ctx)
+		if err != nil {
+			return nil, fmt.Errorf("failed to create add-on [namespace=%s]: %w", params.Namespace, err)
+		}
+
+		if addonRow == nil {
+			return nil, fmt.Errorf("invalid query result: nil add-on received [namespace=%s]", params.Namespace)
+		}
+
+		if len(params.RateCards) > 0 {
+			bulk, err := rateCardBulkCreate(a.db.AddonRateCard, params.RateCards, addonRow.ID, params.Namespace)
+			if err != nil {
+				return nil, fmt.Errorf("failed to bulk create ratecards [namespace=%s id:%s]: %w", params.Namespace, addonRow.ID, err)
+			}
+
+			if err = a.db.AddonRateCard.CreateBulk(bulk...).Exec(ctx); err != nil {
+				return nil, fmt.Errorf("failed to bulk create ratecards [namespace=%s id:%s]: %w", params.Namespace, addonRow.ID, err)
+			}
+		}
+
+		// Refetch newly created addon
+		addonRow, err = a.db.Addon.Query().
+			Where(addondb.And(
+				addondb.Namespace(params.Namespace),
+				addondb.ID(addonRow.ID)),
+			).
+			WithRatecards(
+				AddonEagerLoadRateCardsFn,
+			).
+			First(ctx)
+		if err != nil {
+			return nil, fmt.Errorf("failed to create add-on [namespace=%s]: %w", params.Namespace, err)
+		}
+
+		add, err := FromAddonRow(*addonRow)
+		if err != nil {
+			return nil, fmt.Errorf("failed to cast add-on [namespace=%s id:%s]: %w", params.Namespace, addonRow.ID, err)
+		}
+
+		return add, nil
+	}
+
+	return entutils.TransactingRepo[*addon.Addon, *adapter](ctx, a, fn)
+}
+
+func rateCardBulkCreate(c *entdb.AddonRateCardClient, rateCards productcatalog.RateCards, addonID string, ns string) ([]*entdb.AddonRateCardCreate, error) {
+	bulk := make([]*entdb.AddonRateCardCreate, 0, len(rateCards))
+
+	for _, rateCard := range rateCards {
+		rateCardEntity, err := asAddonRateCardRow(rateCard)
+		if err != nil {
+			return nil, fmt.Errorf("failed to cast ratecard to db entity: %w", err)
+		}
+
+		q := c.Create().
+			SetAddonID(addonID).
+			SetNamespace(ns).
+			SetKey(rateCardEntity.Key).
+			SetType(rateCardEntity.Type).
+			SetName(rateCardEntity.Name).
+			SetNillableDescription(rateCardEntity.Description).
+			SetMetadata(rateCardEntity.Metadata).
+			SetNillableFeatureKey(rateCardEntity.FeatureKey).
+			SetNillableFeaturesID(rateCardEntity.FeatureID).
+			SetEntitlementTemplate(rateCardEntity.EntitlementTemplate).
+			SetNillableBillingCadence(rateCardEntity.BillingCadence).
+			SetDiscounts(rateCardEntity.Discounts)
+
+		if rateCardEntity.TaxConfig != nil {
+			q.SetTaxConfig(rateCardEntity.TaxConfig)
+		}
+
+		q.SetNillableTaxCodeID(rateCardEntity.TaxCodeID)
+		q.SetNillableTaxBehavior(rateCardEntity.TaxBehavior)
+
+		if rateCardEntity.Price != nil {
+			q.SetPrice(rateCardEntity.Price)
+		}
+
+		if rateCardEntity.UnitConfig != nil {
+			q.SetUnitConfig(rateCardEntity.UnitConfig)
+		}
+
+		bulk = append(bulk, q)
+	}
+
+	return bulk, nil
+}
+
+func (a *adapter) DeleteAddon(ctx context.Context, params addon.DeleteAddonInput) error {
+	fn := func(ctx context.Context, a *adapter) (interface{}, error) {
+		if err := params.Validate(); err != nil {
+			return nil, fmt.Errorf("invalid delete add-on parameters: %w", err)
+		}
+
+		add, err := a.GetAddon(ctx, addon.GetAddonInput{
+			NamespacedID: models.NamespacedID{
+				Namespace: params.Namespace,
+				ID:        params.ID,
+			},
+		})
+		if err != nil {
+			if entdb.IsNotFound(err) {
+				return nil, addon.NewNotFoundError(addon.NotFoundErrorParams{
+					Namespace: params.Namespace,
+					ID:        params.ID,
+				})
+			}
+
+			return nil, fmt.Errorf("failed to get add-on: %w", err)
+		}
+
+		deletedAt := time.Now().UTC()
+		err = a.db.Addon.UpdateOneID(add.ID).
+			Where(addondb.Namespace(add.Namespace)).
+			SetDeletedAt(deletedAt).
+			Exec(ctx)
+		if err != nil {
+			if entdb.IsNotFound(err) {
+				return nil, addon.NewNotFoundError(addon.NotFoundErrorParams{
+					Namespace: params.Namespace,
+					ID:        params.ID,
+				})
+			}
+
+			return nil, fmt.Errorf("failed to delete add-on: %w", err)
+		}
+
+		return nil, nil
+	}
+
+	_, resp := entutils.TransactingRepo[interface{}, *adapter](ctx, a, fn)
+
+	return resp
+}
+
+func (a *adapter) GetAddon(ctx context.Context, params addon.GetAddonInput) (*addon.Addon, error) {
+	fn := func(ctx context.Context, a *adapter) (*addon.Addon, error) {
+		if err := params.Validate(); err != nil {
+			return nil, fmt.Errorf("invalid get add-on parameters: %w", err)
+		}
+
+		query := a.db.Addon.Query()
+
+		if params.ID != "" { // get Addon by ID
+			query = query.Where(addondb.And(
+				addondb.Namespace(params.Namespace),
+				addondb.ID(params.ID)),
+			)
+		} else if params.Key != "" {
+			if params.Version == 0 {
+				if params.IncludeLatest { // get add-ons latest version by Key
+					//
+					//	SELECT *
+					//	FROM Addons WHERE (namespace, key, version) IN
+					//	(SELECT namespace, key, MAX(version)
+					//		FROM addons
+					//		WHERE namespace = '$1' and key = '$2'
+					//		GROUP BY (namespace, key)
+					//	)
+					query = query.Where(func(s *sql.Selector) {
+						t := sql.Table(addondb.Table)
+						s.Where(
+							sql.In(
+								t.Wrap(func(b *sql.Builder) {
+									b.IdentComma(addondb.FieldNamespace, addondb.FieldKey, addondb.FieldVersion)
+								}).String(),
+								sql.Select(
+									addondb.FieldNamespace, addondb.FieldKey, sql.Max(addondb.FieldVersion),
+								).
+									From(t).
+									Where(sql.And(
+										sql.EQ(addondb.FieldNamespace, params.Namespace),
+										sql.EQ(addondb.FieldKey, params.Key),
+									)).
+									GroupBy(addondb.FieldNamespace, addondb.FieldKey),
+							),
+						)
+					})
+				} else { // get add-on in active with active status by Key
+					now := time.Now().UTC()
+					query = query.Where(addondb.And(
+						addondb.Namespace(params.Namespace),
+						addondb.Key(params.Key),
+						addondb.EffectiveFromLTE(now),
+						addondb.Or(
+							addondb.EffectiveToGT(now),
+							addondb.EffectiveToIsNil(),
+						),
+						addondb.DeletedAtIsNil(),
+					))
+				}
+			} else { // get add-on by Key and Version
+				query = query.Where(addondb.And(
+					addondb.Namespace(params.Namespace),
+					addondb.Key(params.Key),
+					addondb.Version(params.Version),
+				))
+			}
+		}
+
+		// Eager load RateCards
+		query = query.WithRatecards(
+			AddonEagerLoadRateCardsFn,
+		)
+
+		if params.Expand.PlanAddons {
+			query = query.WithPlans(
+				addonEagerLoadActivePlans,
+			)
+		}
+
+		addonRow, err := query.First(ctx)
+		if err != nil {
+			if entdb.IsNotFound(err) {
+				return nil, addon.NewNotFoundError(addon.NotFoundErrorParams{
+					Namespace: params.Namespace,
+					ID:        params.ID,
+					Key:       params.Key,
+					Version:   params.Version,
+				})
+			}
+
+			return nil, fmt.Errorf("failed to get add-on: %w", err)
+		}
+
+		if addonRow == nil {
+			return nil, fmt.Errorf("invalid query result: nil add-on received")
+		}
+
+		add, err := FromAddonRow(*addonRow)
+		if err != nil {
+			return nil, fmt.Errorf("failed to cast add-on: %w", err)
+		}
+
+		return add, nil
+	}
+
+	return entutils.TransactingRepo[*addon.Addon, *adapter](ctx, a, fn)
+}
+
+var addonEagerLoadActivePlans = func(paq *entdb.PlanAddonQuery) {
+	paq.Where(
+		planaddondb.Or(
+			planaddondb.DeletedAtIsNil(),
+			planaddondb.DeletedAtGT(clock.Now().UTC()),
+		),
+	).WithPlan(func(pq *entdb.PlanQuery) {
+		pq.WithPhases(func(ppq *entdb.PlanPhaseQuery) {
+			ppq.Where(
+				phasedb.Or(
+					phasedb.DeletedAtIsNil(),
+					phasedb.DeletedAtGT(clock.Now().UTC()),
+				),
+			).WithRatecards(func(prcq *entdb.PlanRateCardQuery) {
+				prcq.Where(
+					ratecarddb.Or(
+						ratecarddb.DeletedAtIsNil(),
+						ratecarddb.DeletedAtGT(clock.Now().UTC()),
+					),
+				).WithFeatures().WithTaxCode()
+			})
+		})
+	})
+}
+
+func (a *adapter) UpdateAddon(ctx context.Context, params addon.UpdateAddonInput) (*addon.Addon, error) {
+	fn := func(ctx context.Context, a *adapter) (*addon.Addon, error) {
+		if err := params.Validate(); err != nil {
+			return nil, fmt.Errorf("invalid update add-on parameters: %w", err)
+		}
+
+		add, err := a.GetAddon(ctx, addon.GetAddonInput{
+			NamespacedID: models.NamespacedID{
+				Namespace: params.Namespace,
+				ID:        params.ID,
+			},
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to get add-on: %w", err)
+		}
+
+		if !params.Equal(*add) {
+			query := a.db.Addon.UpdateOneID(add.ID).
+				Where(addondb.Namespace(params.Namespace)).
+				SetNillableName(params.Name).
+				SetNillableDescription(params.Description).
+				SetNillableEffectiveFrom(params.EffectiveFrom).
+				SetNillableEffectiveTo(params.EffectiveTo)
+
+			if params.Metadata != nil {
+				query = query.SetMetadata(*params.Metadata)
+			}
+
+			if params.Annotations != nil {
+				query = query.SetAnnotations(*params.Annotations)
+			}
+
+			if params.InstanceType != nil {
+				query = query.SetInstanceType(*params.InstanceType)
+			}
+
+			err = query.Exec(ctx)
+			if err != nil {
+				return nil, fmt.Errorf("failed to update add-on: %w", err)
+			}
+
+			// Addon needs to be refetched after updated in order to populate all subresources
+			add, err = a.GetAddon(ctx, addon.GetAddonInput{
+				NamespacedID: models.NamespacedID{
+					Namespace: params.Namespace,
+					ID:        params.ID,
+				},
+			})
+			if err != nil {
+				if entdb.IsNotFound(err) {
+					return nil, addon.NewNotFoundError(addon.NotFoundErrorParams{
+						Namespace: params.Namespace,
+						ID:        params.ID,
+					})
+				}
+
+				return nil, fmt.Errorf("failed to get updated add-on: %w", err)
+			}
+		}
+
+		// Return early if there are no updates for AddonPhases
+		if params.RateCards == nil {
+			return add, nil
+		}
+
+		// Delete all existing ratecards
+		_, err = a.db.AddonRateCard.Delete().
+			Where(addonratecarddb.AddonID(add.ID)).
+			Exec(ctx)
+		if err != nil {
+			return nil, fmt.Errorf("failed to delete add-on ratecards: %w", err)
+		}
+
+		if len(*params.RateCards) > 0 {
+			bulk, err := rateCardBulkCreate(a.db.AddonRateCard, *params.RateCards, add.ID, params.Namespace)
+			if err != nil {
+				return nil, fmt.Errorf("failed to bulk create ratecards [namespace=%s id:%s]: %w", params.Namespace, add.ID, err)
+			}
+
+			if err = a.db.AddonRateCard.CreateBulk(bulk...).Exec(ctx); err != nil {
+				return nil, fmt.Errorf("failed to bulk create ratecards [namespace=%s id:%s]: %w", params.Namespace, add.ID, err)
+			}
+		}
+
+		// Refetch updated add-on
+		addonRow, err := a.db.Addon.Query().
+			Where(addondb.And(
+				addondb.Namespace(params.Namespace),
+				addondb.ID(add.ID)),
+			).
+			WithRatecards(
+				AddonEagerLoadRateCardsFn,
+			).
+			First(ctx)
+		if err != nil {
+			return nil, fmt.Errorf("failed to update add-on [namespace=%s]: %w", params.Namespace, err)
+		}
+
+		add, err = FromAddonRow(*addonRow)
+		if err != nil {
+			return nil, fmt.Errorf("failed to cast updated add-on [namespace=%s id:%s]: %w", params.Namespace, addonRow.ID, err)
+		}
+
+		return add, nil
+	}
+
+	return entutils.TransactingRepo[*addon.Addon, *adapter](ctx, a, fn)
+}
+
+var AddonEagerLoadRateCardsFn = func(q *entdb.AddonRateCardQuery) {
+	q.Where(
+		addonratecarddb.Or(
+			addonratecarddb.DeletedAtIsNil(),
+			addonratecarddb.DeletedAtGT(clock.Now().UTC()),
+		))
+	rateCardEagerLoadFeaturesFn(q)
+	rateCardEagerLoadTaxCodesFn(q)
+}
+
+var rateCardEagerLoadFeaturesFn = func(q *entdb.AddonRateCardQuery) {
+	q.WithFeatures()
+}
+
+var rateCardEagerLoadTaxCodesFn = func(q *entdb.AddonRateCardQuery) {
+	q.WithTaxCode()
+}

openmeter/productcatalog/addon/adapter/mapping.go

@@ -0,0 +1,398 @@
+package adapter
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/invopop/gobl/currency"
+	"github.com/samber/lo"
+
+	entdb "github.com/openmeterio/openmeter/openmeter/ent/db"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/addon"
+	taxcodeadapter "github.com/openmeterio/openmeter/openmeter/taxcode/adapter"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+func FromAddonRow(a entdb.Addon) (*addon.Addon, error) {
+	aa := &addon.Addon{
+		NamespacedID: models.NamespacedID{
+			Namespace: a.Namespace,
+			ID:        a.ID,
+		},
+		ManagedModel: models.ManagedModel{
+			CreatedAt: a.CreatedAt,
+			UpdatedAt: a.UpdatedAt,
+			DeletedAt: a.DeletedAt,
+		},
+		AddonMeta: productcatalog.AddonMeta{
+			Key:          a.Key,
+			Name:         a.Name,
+			Description:  a.Description,
+			Metadata:     a.Metadata,
+			Annotations:  a.Annotations,
+			Version:      a.Version,
+			Currency:     currency.Code(a.Currency),
+			InstanceType: a.InstanceType,
+			EffectivePeriod: productcatalog.EffectivePeriod{
+				EffectiveFrom: a.EffectiveFrom,
+				EffectiveTo:   a.EffectiveTo,
+			},
+		},
+	}
+
+	// Set Rate Cards
+
+	if len(a.Edges.Ratecards) > 0 {
+		aa.RateCards = make(addon.RateCards, 0, len(a.Edges.Ratecards))
+		for _, edge := range a.Edges.Ratecards {
+			if edge == nil {
+				continue
+			}
+
+			ratecard, err := FromAddonRateCardRow(*edge)
+			if err != nil {
+				return nil, fmt.Errorf("invalid ratecard [namespace=%s key=%s]: %w", aa.Namespace, edge.Key, err)
+			}
+
+			aa.RateCards = append(aa.RateCards, *ratecard)
+		}
+	}
+
+	plans, err := a.Edges.PlansOrErr()
+	if err != nil {
+		aa.Plans = nil
+	} else {
+		planAddons := make([]addon.Plan, 0, len(plans))
+
+		for _, plan := range plans {
+			if plan == nil {
+				continue
+			}
+
+			planAddon, err := FromPlanAddonRow(*plan)
+			if err != nil {
+				return nil, fmt.Errorf("invalid plan add-on assignment %s: %w", plan.ID, err)
+			}
+
+			planAddons = append(planAddons, *planAddon)
+		}
+
+		aa.Plans = &planAddons
+	}
+
+	return aa, nil
+}
+
+func FromAddonRateCardRow(r entdb.AddonRateCard) (*addon.RateCard, error) {
+	meta := productcatalog.RateCardMeta{
+		Key:                 r.Key,
+		Name:                r.Name,
+		Description:         r.Description,
+		Metadata:            r.Metadata,
+		EntitlementTemplate: r.EntitlementTemplate,
+		FeatureKey:          r.FeatureKey,
+		FeatureID:           r.FeatureID,
+		TaxConfig:           r.TaxConfig,
+		Price:               r.Price,
+		Discounts:           lo.FromPtr(r.Discounts),
+		UnitConfig:          r.UnitConfig,
+	}
+
+	if r.FeatureID != nil || r.FeatureKey != nil {
+		ratecardFeature, err := r.Edges.FeaturesOrErr()
+		//if err != nil {
+		//	return nil, errors.New("feature is not loaded for ratecard")
+		//}
+		//
+		//meta.SetFeature(&ratecardFeature.ID, &ratecardFeature.Key)
+
+		// FIXME(chrisgacsal): temporary fix until data is migrated
+		if err == nil && ratecardFeature != nil {
+			meta.SetFeature(&ratecardFeature.ID, &ratecardFeature.Key)
+		}
+	}
+
+	// Map TaxCode if eagerly loaded.
+	taxCodeRow, err := r.Edges.TaxCodeOrErr()
+	if err == nil {
+		tc, err := taxcodeadapter.MapTaxCodeFromEntity(taxCodeRow)
+		if err != nil {
+			return nil, fmt.Errorf("invalid tax code for rate card %s: %w", r.ID, err)
+		}
+
+		meta.TaxCode = &tc
+	}
+
+	// Backfill legacy TaxConfig fields from new columns and TaxCode entity.
+	meta.TaxConfig = productcatalog.BackfillTaxConfig(meta.TaxConfig, r.TaxBehavior, meta.TaxCode)
+
+	// Get billing cadence
+
+	billingCadence, err := r.BillingCadence.ParsePtrOrNil()
+	if err != nil {
+		return nil, fmt.Errorf("invalid ratecard [namespace=%s key=%s]: billing cadence: %w", r.Namespace, r.Key, err)
+	}
+
+	// Managed fields
+
+	managed := addon.RateCardManagedFields{
+		ManagedModel: models.ManagedModel{
+			CreatedAt: r.CreatedAt,
+			UpdatedAt: r.UpdatedAt,
+			DeletedAt: r.DeletedAt,
+		},
+		NamespacedID: models.NamespacedID{
+			Namespace: r.Namespace,
+			ID:        r.ID,
+		},
+		AddonID: r.AddonID,
+	}
+
+	var ratecard *addon.RateCard
+
+	switch r.Type {
+	case productcatalog.FlatFeeRateCardType:
+		ratecard = &addon.RateCard{
+			RateCardManagedFields: managed,
+			RateCard: &productcatalog.FlatFeeRateCard{
+				RateCardMeta:   meta,
+				BillingCadence: billingCadence,
+			},
+		}
+	case productcatalog.UsageBasedRateCardType:
+		ratecard = &addon.RateCard{
+			RateCardManagedFields: managed,
+			RateCard: &productcatalog.UsageBasedRateCard{
+				RateCardMeta:   meta,
+				BillingCadence: lo.FromPtr(billingCadence),
+			},
+		}
+	default:
+		return nil, fmt.Errorf("invalid ratecard [namespace=%s key=%s]: invalid type %s: %w", r.Namespace, r.Key, r.Type, err)
+	}
+
+	return ratecard, nil
+}
+
+func FromPlanAddonRow(a entdb.PlanAddon) (*addon.Plan, error) {
+	planAddon := &addon.Plan{
+		NamespacedID: models.NamespacedID{
+			Namespace: a.Namespace,
+			ID:        a.ID,
+		},
+		ManagedModel: models.ManagedModel{
+			CreatedAt: a.CreatedAt,
+			UpdatedAt: a.UpdatedAt,
+			DeletedAt: a.DeletedAt,
+		},
+		PlanAddonMeta: productcatalog.PlanAddonMeta{
+			Metadata:    a.Metadata,
+			Annotations: a.Annotations,
+			PlanAddonConfig: productcatalog.PlanAddonConfig{
+				FromPlanPhase: a.FromPlanPhase,
+				MaxQuantity:   a.MaxQuantity,
+			},
+		},
+	}
+
+	// Set Plan
+
+	plan, err := a.Edges.PlanOrErr()
+	if err != nil {
+		return nil, errors.New("failed to cast plan: plan is not loaded")
+	}
+
+	pp, err := FromPlanRow(*plan)
+	if err != nil {
+		return nil, fmt.Errorf("failed to cast add-on: %w", err)
+	}
+
+	planAddon.Plan = *pp
+
+	return planAddon, nil
+}
+
+func FromPlanRow(p entdb.Plan) (*productcatalog.Plan, error) {
+	billingCadence, err := p.BillingCadence.Parse()
+	if err != nil {
+		return nil, fmt.Errorf("invalid billing cadence %s: %w", p.BillingCadence, err)
+	}
+
+	pp := &productcatalog.Plan{
+		PlanMeta: productcatalog.PlanMeta{
+			Key:         p.Key,
+			Name:        p.Name,
+			Description: p.Description,
+			Metadata:    p.Metadata,
+			Version:     p.Version,
+			Currency:    currency.Code(p.Currency),
+			EffectivePeriod: productcatalog.EffectivePeriod{
+				EffectiveFrom: p.EffectiveFrom,
+				EffectiveTo:   p.EffectiveTo,
+			},
+			BillingCadence:  billingCadence,
+			ProRatingConfig: p.ProRatingConfig,
+			SettlementMode:  p.SettlementMode,
+		},
+	}
+
+	if len(p.Edges.Phases) > 0 {
+		phases := make([]productcatalog.Phase, len(p.Edges.Phases))
+		for _, edge := range p.Edges.Phases {
+			if edge == nil {
+				continue
+			}
+
+			phase, err := FromPlanPhaseRow(*edge)
+			if err != nil {
+				return nil, fmt.Errorf("invalid phase %s: %w", edge.ID, err)
+			}
+
+			phases[edge.Index] = *phase
+		}
+
+		if len(phases) > 0 {
+			pp.Phases = phases
+		}
+	}
+
+	return pp, nil
+}
+
+func FromPlanPhaseRow(p entdb.PlanPhase) (*productcatalog.Phase, error) {
+	pp := &productcatalog.Phase{
+		PhaseMeta: productcatalog.PhaseMeta{
+			Key:         p.Key,
+			Name:        p.Name,
+			Description: p.Description,
+			Metadata:    p.Metadata,
+		},
+	}
+
+	// Set Interval
+
+	duration, err := p.Duration.ParsePtrOrNil()
+	if err != nil {
+		return nil, fmt.Errorf("invalid duration %v: %w", p.Duration, err)
+	}
+
+	pp.Duration = duration
+
+	// Set Rate Cards
+
+	if len(p.Edges.Ratecards) > 0 {
+		pp.RateCards = make([]productcatalog.RateCard, 0, len(p.Edges.Ratecards))
+		for _, edge := range p.Edges.Ratecards {
+			if edge == nil {
+				continue
+			}
+
+			ratecard, err := FromPlanRateCardRow(*edge)
+			if err != nil {
+				return nil, fmt.Errorf("invalid rate card %s: %w", edge.ID, err)
+			}
+
+			pp.RateCards = append(pp.RateCards, ratecard)
+		}
+	}
+
+	return pp, nil
+}
+
+func FromPlanRateCardRow(r entdb.PlanRateCard) (productcatalog.RateCard, error) {
+	meta := productcatalog.RateCardMeta{
+		Key:                 r.Key,
+		Name:                r.Name,
+		Description:         r.Description,
+		Metadata:            r.Metadata,
+		FeatureID:           r.FeatureID,
+		FeatureKey:          r.FeatureKey,
+		EntitlementTemplate: r.EntitlementTemplate,
+		TaxConfig:           r.TaxConfig,
+		Price:               r.Price,
+		Discounts:           lo.FromPtr(r.Discounts),
+		UnitConfig:          r.UnitConfig,
+	}
+
+	// Map TaxCode if eagerly loaded.
+	taxCodeRow, err := r.Edges.TaxCodeOrErr()
+	if err == nil {
+		tc, err := taxcodeadapter.MapTaxCodeFromEntity(taxCodeRow)
+		if err != nil {
+			return nil, fmt.Errorf("invalid tax code for rate card %s: %w", r.ID, err)
+		}
+
+		meta.TaxCode = &tc
+	}
+
+	// Backfill legacy TaxConfig fields from new columns and TaxCode entity.
+	meta.TaxConfig = productcatalog.BackfillTaxConfig(meta.TaxConfig, r.TaxBehavior, meta.TaxCode)
+
+	// Get billing cadence
+
+	billingCadence, err := r.BillingCadence.ParsePtrOrNil()
+	if err != nil {
+		return nil, fmt.Errorf("invalid rate card billing cadence %s: %w", r.ID, err)
+	}
+
+	var ratecard productcatalog.RateCard
+
+	switch r.Type {
+	case productcatalog.FlatFeeRateCardType:
+		ratecard = &productcatalog.FlatFeeRateCard{
+			RateCardMeta:   meta,
+			BillingCadence: billingCadence,
+		}
+	case productcatalog.UsageBasedRateCardType:
+		ratecard = &productcatalog.UsageBasedRateCard{
+			RateCardMeta:   meta,
+			BillingCadence: lo.FromPtr(billingCadence),
+		}
+	default:
+		return nil, fmt.Errorf("invalid RateCard type %s", r.Type)
+	}
+
+	return ratecard, nil
+}
+
+func asAddonRateCardRow(r productcatalog.RateCard) (entdb.AddonRateCard, error) {
+	meta := r.AsMeta()
+
+	ratecard := entdb.AddonRateCard{
+		Key:                 meta.Key,
+		Metadata:            meta.Metadata,
+		Name:                meta.Name,
+		Description:         meta.Description,
+		EntitlementTemplate: meta.EntitlementTemplate,
+		TaxConfig:           meta.TaxConfig,
+		FeatureKey:          meta.FeatureKey,
+		FeatureID:           meta.FeatureID,
+		Price:               meta.Price,
+		Type:                r.Type(),
+		Discounts:           lo.EmptyableToPtr(meta.Discounts),
+		UnitConfig:          meta.UnitConfig,
+	}
+
+	if managed, ok := r.(addon.ManagedRateCard); ok {
+		managedFields := managed.ManagedFields()
+		ratecard.Namespace = managedFields.Namespace
+		ratecard.ID = managedFields.ID
+	}
+
+	switch v := r.(type) {
+	case *productcatalog.FlatFeeRateCard:
+		ratecard.BillingCadence = v.BillingCadence.ISOStringPtrOrNil()
+	case *productcatalog.UsageBasedRateCard:
+		ratecard.BillingCadence = v.BillingCadence.ISOStringPtrOrNil()
+	default:
+		return ratecard, fmt.Errorf("invalid ratecard [key=%s]: invalid type: %T", r.Key(), r)
+	}
+
+	if meta.TaxConfig != nil {
+		ratecard.TaxCodeID = meta.TaxConfig.TaxCodeID
+		ratecard.TaxBehavior = meta.TaxConfig.Behavior
+	}
+
+	return ratecard, nil
+}

openmeter/productcatalog/addon/addon.go

@@ -0,0 +1,62 @@
+package addon
+
+import (
+	"errors"
+
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+var (
+	_ models.Validator              = (*Addon)(nil)
+	_ models.CustomValidator[Addon] = (*Addon)(nil)
+)
+
+type Addon struct {
+	models.NamespacedID
+	models.ManagedModel
+
+	productcatalog.AddonMeta
+
+	// RateCards
+	RateCards RateCards `json:"rateCards"`
+
+	// Plans contains the list of Plans assigned to this Addon. It is only provided if the Addon was fetched
+	// with Plans being expanded.
+	Plans *[]Plan `json:"plans,omitempty"`
+}
+
+func (a Addon) ValidateWith(validators ...models.ValidatorFunc[Addon]) error {
+	return models.Validate(a, validators...)
+}
+
+func (a Addon) Validate() error {
+	var errs []error
+
+	if err := a.NamespacedID.Validate(); err != nil {
+		errs = append(errs, err)
+	}
+
+	if err := a.ManagedModel.Validate(); err != nil {
+		errs = append(errs, err)
+	}
+
+	if err := a.AddonMeta.Validate(); err != nil {
+		errs = append(errs, err)
+	}
+
+	for _, rateCard := range a.RateCards {
+		if err := rateCard.Validate(); err != nil {
+			errs = append(errs, err)
+		}
+	}
+
+	return models.NewNillableGenericValidationError(errors.Join(errs...))
+}
+
+func (a Addon) AsProductCatalogAddon() productcatalog.Addon {
+	return productcatalog.Addon{
+		AddonMeta: a.AddonMeta,
+		RateCards: a.RateCards.AsProductCatalogRateCards(),
+	}
+}

openmeter/productcatalog/addon/assert.go

@@ -0,0 +1,134 @@
+package addon
+
+import (
+	"testing"
+
+	"github.com/samber/lo"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+)
+
+func AssertAddonCreateInputEqual(t *testing.T, i CreateAddonInput, a Addon) {
+	t.Helper()
+
+	assert.Equalf(t, i.Namespace, a.Namespace, "create input: namespace mismatch")
+	assert.Equalf(t, i.Key, a.Key, "create input: key mismatch")
+	assert.Equalf(t, i.Name, a.Name, "create input: name mismatch")
+	assert.Equalf(t, i.Description, a.Description, "create input: description mismatch")
+	assert.Equalf(t, i.Currency, a.Currency, "create input: currency mismatch")
+	assert.Equalf(t, i.Metadata, a.Metadata, "metadata mismatch")
+	assert.Equalf(t, i.Annotations, a.Annotations, "annotations mismatch")
+
+	AssertAddonRateCardsEqual(t, i.RateCards, a.RateCards.AsProductCatalogRateCards())
+}
+
+func AssertAddonUpdateInputEqual(t *testing.T, i UpdateAddonInput, a Addon) {
+	t.Helper()
+
+	assert.Equalf(t, i.Namespace, a.Namespace, "update input: namespace mismatch")
+
+	if i.Name != nil {
+		assert.Equalf(t, *i.Name, a.Name, "update input: name mismatch")
+	}
+
+	if i.Description != nil {
+		assert.Equalf(t, lo.FromPtr(i.Description), lo.FromPtr(a.Description), "update input: description mismatch")
+	}
+
+	if i.Metadata != nil {
+		assert.Equalf(t, *i.Metadata, a.Metadata, "metadata mismatch")
+	}
+
+	if i.Annotations != nil {
+		assert.Equalf(t, *i.Annotations, a.Annotations, "annotations mismatch")
+	}
+
+	if i.RateCards != nil {
+		AssertAddonRateCardsEqual(t, *i.RateCards, a.RateCards.AsProductCatalogRateCards())
+	}
+}
+
+func AssertAddonEqual(t *testing.T, expected, actual Addon) {
+	t.Helper()
+
+	assert.Equalf(t, expected.Key, actual.Key, "key mismatch")
+	assert.Equalf(t, expected.Name, actual.Name, "name mismatch")
+	assert.Equalf(t, expected.Description, actual.Description, "description mismatch")
+	assert.Equalf(t, expected.Currency, actual.Currency, "currency mismatch")
+	assert.Equalf(t, expected.Metadata, actual.Metadata, "metadata mismatch")
+	assert.Equalf(t, expected.Annotations, actual.Annotations, "annotations mismatch")
+
+	AssertAddonRateCardsEqual(t, expected.RateCards.AsProductCatalogRateCards(), actual.RateCards.AsProductCatalogRateCards())
+}
+
+func AssertAddonRateCardsEqual(t *testing.T, r1, r2 productcatalog.RateCards) {
+	t.Helper()
+
+	assert.Equalf(t, len(r1), len(r2), "number of RateCards mismatch")
+
+	r1Map := func() map[string]productcatalog.RateCard {
+		m := make(map[string]productcatalog.RateCard, len(r1))
+		for _, v := range r1 {
+			m[v.Key()] = v
+		}
+
+		return m
+	}()
+
+	r2Map := func() map[string]productcatalog.RateCard {
+		m := make(map[string]productcatalog.RateCard, len(r2))
+		for _, v := range r2 {
+			m[v.Key()] = v
+		}
+
+		return m
+	}()
+
+	visited := make(map[string]struct{})
+	for phase1Key, rateCard1 := range r1Map {
+		rateCard2, ok := r2Map[phase1Key]
+		require.Truef(t, ok, "missing RateCard key")
+
+		AssertRateCardEqual(t, rateCard1, rateCard2)
+
+		visited[phase1Key] = struct{}{}
+	}
+
+	for phase2Key := range r2Map {
+		_, ok := visited[phase2Key]
+		require.Truef(t, ok, "missing RateCard key")
+	}
+}
+
+func AssertRateCardEqual(t *testing.T, r1, r2 productcatalog.RateCard) {
+	t.Helper()
+
+	assert.Equalf(t, r1.Type(), r2.Type(), "type mismatch")
+
+	m1 := r1.AsMeta()
+	m2 := r2.AsMeta()
+
+	assert.Equalf(t, m1.Key, m2.Key, "key mismatch")
+	assert.Equalf(t, m1.Name, m2.Name, "name mismatch")
+	assert.Equalf(t, lo.FromPtr(m1.Description), lo.FromPtr(m2.Description), "description mismatch")
+
+	assert.Truef(t, m1.Metadata.Equal(m2.Metadata), "metadata mismatch")
+
+	assert.Equalf(t, m1.FeatureKey, m2.FeatureKey, "feature key mismatch")
+	assert.Equalf(t, m1.FeatureID, m2.FeatureID, "feature id mismatch")
+
+	assert.Truef(t, m1.EntitlementTemplate.Equal(m2.EntitlementTemplate), "entitlement template mismatch")
+
+	assert.Truef(t, m1.TaxConfig.Equal(m2.TaxConfig), "tax config mismatch")
+
+	assert.Truef(t, m1.Price.Equal(m2.Price), "price mismatch")
+
+	assert.Truef(t, m1.UnitConfig.Equal(m2.UnitConfig), "unit config mismatch")
+
+	billingCadence1 := r1.GetBillingCadence().ISOStringPtrOrNil()
+	billingCadence2 := r2.GetBillingCadence().ISOStringPtrOrNil()
+
+	assert.Equal(t, billingCadence1, billingCadence2)
+}

openmeter/productcatalog/addon/errors.go

@@ -0,0 +1,72 @@
+package addon
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+var _ error = (*NotFoundError)(nil)
+
+type NotFoundErrorParams struct {
+	Namespace string
+	ID        string
+	Key       string
+	Version   int
+}
+
+func NewNotFoundError(e NotFoundErrorParams) *NotFoundError {
+	var m string
+
+	if e.Namespace != "" {
+		m += fmt.Sprintf(" namespace=%s", e.Namespace)
+	}
+
+	if e.ID != "" {
+		m += fmt.Sprintf(" id=%s", e.ID)
+	}
+
+	if e.Key != "" {
+		m += fmt.Sprintf(" key=%s", e.Key)
+	}
+
+	if e.Version != 0 {
+		m += fmt.Sprintf(" version=%d", e.Version)
+	}
+
+	if len(m) > 0 {
+		m = fmt.Sprintf("add-on not found. [%s]", m[1:])
+	} else {
+		m = "add-on not found"
+	}
+
+	return &NotFoundError{
+		err: models.NewGenericNotFoundError(
+			errors.New(m),
+		),
+	}
+}
+
+var _ models.GenericError = &NotFoundError{}
+
+type NotFoundError struct {
+	err error
+}
+
+func (e *NotFoundError) Error() string {
+	return e.err.Error()
+}
+
+func (e *NotFoundError) Unwrap() error {
+	return e.err
+}
+
+func IsNotFound(err error) bool {
+	if err == nil {
+		return false
+	}
+	var e *NotFoundError
+
+	return errors.As(err, &e)
+}

openmeter/productcatalog/addon/errors_test.go

@@ -0,0 +1,94 @@
+package addon
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestIsNotFoundError(t *testing.T) {
+	tests := []struct {
+		Name          string
+		Error         error
+		ExpectedError bool
+	}{
+		{
+			Name: "Valid",
+			Error: NewNotFoundError(NotFoundErrorParams{
+				Namespace: "test",
+				ID:        "test",
+			}),
+			ExpectedError: true,
+		},
+		{
+			Name: "Wrapped",
+			Error: errors.Join(
+				fmt.Errorf("wrapped: %w", NewNotFoundError(NotFoundErrorParams{
+					Namespace: "test",
+					ID:        "test",
+				})),
+			),
+			ExpectedError: true,
+		},
+		{
+			Name:          "Invalid",
+			Error:         errors.New("test error"),
+			ExpectedError: false,
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.Name, func(t *testing.T) {
+			assert.Equal(t, test.ExpectedError, IsNotFound(test.Error))
+		})
+	}
+}
+
+func TestIsNotFoundError_String(t *testing.T) {
+	tests := []struct {
+		Name          string
+		Error         error
+		ExpectedError string
+	}{
+		{
+			Name: "ID",
+			Error: NewNotFoundError(NotFoundErrorParams{
+				Namespace: "namespace",
+				ID:        "id",
+			}),
+			ExpectedError: "not found error: add-on not found. [namespace=namespace id=id]",
+		},
+		{
+			Name: "Key",
+			Error: NewNotFoundError(NotFoundErrorParams{
+				Namespace: "namespace",
+				Key:       "key",
+			}),
+			ExpectedError: "not found error: add-on not found. [namespace=namespace key=key]",
+		},
+		{
+			Name: "KeyVersion",
+			Error: NewNotFoundError(NotFoundErrorParams{
+				Namespace: "namespace",
+				Key:       "key",
+				Version:   1,
+			}),
+			ExpectedError: "not found error: add-on not found. [namespace=namespace key=key version=1]",
+		},
+		{
+			Name:          "Default",
+			Error:         NewNotFoundError(NotFoundErrorParams{}),
+			ExpectedError: "not found error: add-on not found",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.Name, func(t *testing.T) {
+			t.Logf("%v", test.Error)
+
+			assert.Equal(t, test.ExpectedError, test.Error.Error())
+		})
+	}
+}

openmeter/productcatalog/addon/event.go

@@ -0,0 +1,240 @@
+package addon
+
+import (
+	"context"
+	"errors"
+
+	"github.com/oklog/ulid/v2"
+	"github.com/samber/lo"
+
+	"github.com/openmeterio/openmeter/openmeter/event/metadata"
+	"github.com/openmeterio/openmeter/openmeter/session"
+)
+
+const (
+	AddonEventSubsystem   metadata.EventSubsystem = "addon"
+	AddonCreateEventName  metadata.EventName      = "addon.created"
+	AddonUpdateEventName  metadata.EventName      = "addon.updated"
+	AddonDeleteEventName  metadata.EventName      = "addon.deleted"
+	AddonPublishEventName metadata.EventName      = "addon.published"
+	AddonArchiveEventName metadata.EventName      = "addon.archived"
+)
+
+// NewAddonCreateEvent creates a new Addon create event
+func NewAddonCreateEvent(ctx context.Context, addon *Addon) AddonCreateEvent {
+	return AddonCreateEvent{
+		Addon:  addon,
+		UserID: session.GetSessionUserID(ctx),
+	}
+}
+
+// AddonCreateEvent is an event that is emitted when an Addon is created
+type AddonCreateEvent struct {
+	Addon  *Addon  `json:"addon"`
+	UserID *string `json:"userId,omitempty"`
+}
+
+func (e AddonCreateEvent) EventName() string {
+	return metadata.GetEventName(metadata.EventType{
+		Subsystem: AddonEventSubsystem,
+		Name:      AddonCreateEventName,
+		Version:   "v1",
+	})
+}
+
+func (e AddonCreateEvent) EventMetadata() metadata.EventMetadata {
+	resourcePath := metadata.ComposeResourcePath(e.Addon.Namespace, metadata.EntityAddon, e.Addon.ID)
+
+	return metadata.EventMetadata{
+		ID:      ulid.Make().String(),
+		Source:  resourcePath,
+		Subject: resourcePath,
+		Time:    e.Addon.CreatedAt,
+	}
+}
+
+func (e AddonCreateEvent) Validate() error {
+	var errs []error
+
+	if e.Addon == nil {
+		errs = append(errs, errors.New("add-on is required"))
+	}
+
+	return errors.Join(errs...)
+}
+
+// NewAddonUpdateEvent creates a new Addon update event
+func NewAddonUpdateEvent(ctx context.Context, addon *Addon) AddonUpdateEvent {
+	return AddonUpdateEvent{
+		Addon:  addon,
+		UserID: session.GetSessionUserID(ctx),
+	}
+}
+
+// AddonUpdateEvent is an event that is emitted when an Addon is updated
+type AddonUpdateEvent struct {
+	Addon  *Addon  `json:"addon"`
+	UserID *string `json:"userId,omitempty"`
+}
+
+func (e AddonUpdateEvent) EventName() string {
+	return metadata.GetEventName(metadata.EventType{
+		Subsystem: AddonEventSubsystem,
+		Name:      AddonUpdateEventName,
+		Version:   "v1",
+	})
+}
+
+func (e AddonUpdateEvent) EventMetadata() metadata.EventMetadata {
+	resourcePath := metadata.ComposeResourcePath(e.Addon.Namespace, metadata.EntityAddon, e.Addon.ID)
+
+	return metadata.EventMetadata{
+		ID:      ulid.Make().String(),
+		Source:  resourcePath,
+		Subject: resourcePath,
+		Time:    e.Addon.UpdatedAt,
+	}
+}
+
+func (e AddonUpdateEvent) Validate() error {
+	var errs []error
+
+	if e.Addon == nil {
+		errs = append(errs, errors.New("add-on is required"))
+	}
+
+	return errors.Join(errs...)
+}
+
+// NewAddonDeleteEvent creates a new Addon delete event
+func NewAddonDeleteEvent(ctx context.Context, addon *Addon) AddonDeleteEvent {
+	return AddonDeleteEvent{
+		Addon:  addon,
+		UserID: session.GetSessionUserID(ctx),
+	}
+}
+
+// AddonDeleteEvent is an event that is emitted when an Addon is deleted
+type AddonDeleteEvent struct {
+	Addon  *Addon  `json:"addon"`
+	UserID *string `json:"userId,omitempty"`
+}
+
+func (e AddonDeleteEvent) EventName() string {
+	return metadata.GetEventName(metadata.EventType{
+		Subsystem: AddonEventSubsystem,
+		Name:      AddonDeleteEventName,
+		Version:   "v1",
+	})
+}
+
+func (e AddonDeleteEvent) EventMetadata() metadata.EventMetadata {
+	resourcePath := metadata.ComposeResourcePath(e.Addon.Namespace, metadata.EntityAddon, e.Addon.ID)
+
+	return metadata.EventMetadata{
+		ID:      ulid.Make().String(),
+		Source:  resourcePath,
+		Subject: resourcePath,
+		Time:    lo.FromPtr(e.Addon.DeletedAt),
+	}
+}
+
+func (e AddonDeleteEvent) Validate() error {
+	var errs []error
+
+	if e.Addon == nil {
+		errs = append(errs, errors.New("add-on is required"))
+	}
+
+	if e.Addon.DeletedAt == nil {
+		errs = append(errs, errors.New("add-on deleted at is required"))
+	}
+
+	return errors.Join(errs...)
+}
+
+// NewAddonPublishEvent creates a new Addon publish event
+func NewAddonPublishEvent(ctx context.Context, Addon *Addon) AddonPublishEvent {
+	return AddonPublishEvent{
+		Addon:  Addon,
+		UserID: session.GetSessionUserID(ctx),
+	}
+}
+
+// AddonPublishEvent is an event that is emitted when an Addon is published
+type AddonPublishEvent struct {
+	Addon  *Addon  `json:"addon"`
+	UserID *string `json:"userId,omitempty"`
+}
+
+func (e AddonPublishEvent) EventName() string {
+	return metadata.GetEventName(metadata.EventType{
+		Subsystem: AddonEventSubsystem,
+		Name:      AddonPublishEventName,
+		Version:   "v1",
+	})
+}
+
+func (e AddonPublishEvent) EventMetadata() metadata.EventMetadata {
+	resourcePath := metadata.ComposeResourcePath(e.Addon.Namespace, metadata.EntityAddon, e.Addon.ID)
+
+	return metadata.EventMetadata{
+		ID:      ulid.Make().String(),
+		Source:  resourcePath,
+		Subject: resourcePath,
+		Time:    e.Addon.UpdatedAt,
+	}
+}
+
+func (e AddonPublishEvent) Validate() error {
+	var errs []error
+
+	if e.Addon == nil {
+		errs = append(errs, errors.New("add-on is required"))
+	}
+
+	return errors.Join(errs...)
+}
+
+// NewAddonArchiveEvent creates a new Addon archive event
+func NewAddonArchiveEvent(ctx context.Context, Addon *Addon) AddonArchiveEvent {
+	return AddonArchiveEvent{
+		Addon:  Addon,
+		UserID: session.GetSessionUserID(ctx),
+	}
+}
+
+// AddonArchiveEvent is an event that is emitted when an Addon is archived
+type AddonArchiveEvent struct {
+	Addon  *Addon  `json:"addon"`
+	UserID *string `json:"userId,omitempty"`
+}
+
+func (e AddonArchiveEvent) EventName() string {
+	return metadata.GetEventName(metadata.EventType{
+		Subsystem: AddonEventSubsystem,
+		Name:      AddonArchiveEventName,
+		Version:   "v1",
+	})
+}
+
+func (e AddonArchiveEvent) EventMetadata() metadata.EventMetadata {
+	resourcePath := metadata.ComposeResourcePath(e.Addon.Namespace, metadata.EntityAddon, e.Addon.ID)
+
+	return metadata.EventMetadata{
+		ID:      ulid.Make().String(),
+		Source:  resourcePath,
+		Subject: resourcePath,
+		Time:    e.Addon.UpdatedAt,
+	}
+}
+
+func (e AddonArchiveEvent) Validate() error {
+	var errs []error
+
+	if e.Addon == nil {
+		errs = append(errs, errors.New("add-on is required"))
+	}
+
+	return errors.Join(errs...)
+}

openmeter/productcatalog/addon/httpdriver/addon.go

@@ -0,0 +1,398 @@
+package httpdriver
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+
+	"github.com/samber/lo"
+
+	"github.com/openmeterio/openmeter/api"
+	"github.com/openmeterio/openmeter/openmeter/notification"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/addon"
+	productcataloghttp "github.com/openmeterio/openmeter/openmeter/productcatalog/http"
+	"github.com/openmeterio/openmeter/pkg/clock"
+	"github.com/openmeterio/openmeter/pkg/defaultx"
+	"github.com/openmeterio/openmeter/pkg/filter"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+	"github.com/openmeterio/openmeter/pkg/ref"
+	"github.com/openmeterio/openmeter/pkg/sortx"
+)
+
+type (
+	ListAddonsRequest  = addon.ListAddonsInput
+	ListAddonsResponse = api.AddonPaginatedResponse
+	ListAddonsParams   = api.ListAddonsParams
+	ListAddonsHandler  httptransport.HandlerWithArgs[ListAddonsRequest, ListAddonsResponse, ListAddonsParams]
+)
+
+func (h *handler) ListAddons() ListAddonsHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, params ListAddonsParams) (ListAddonsRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return ListAddonsRequest{}, fmt.Errorf("failed to resolve namespace [namespace=%s]: %w", ns, err)
+			}
+
+			var statusFilter []productcatalog.AddonStatus
+			if params.Status != nil {
+				statusFilter = lo.Map(*params.Status, func(status api.AddonStatus, _ int) productcatalog.AddonStatus {
+					return productcatalog.AddonStatus(status)
+				})
+			}
+
+			req := ListAddonsRequest{
+				OrderBy: addon.OrderBy(lo.FromPtrOr(params.OrderBy, api.AddonOrderById)),
+				Order:   sortx.Order(defaultx.WithDefault(params.Order, api.SortOrderDESC)),
+				Page: pagination.Page{
+					PageSize:   defaultx.WithDefault(params.PageSize, notification.DefaultPageSize),
+					PageNumber: defaultx.WithDefault(params.Page, notification.DefaultPageNumber),
+				},
+				Namespaces:     []string{ns},
+				KeyVersions:    lo.FromPtr(params.KeyVersion),
+				IncludeDeleted: lo.FromPtr(params.IncludeDeleted),
+				Status:         statusFilter,
+				// The v1 API cannot represent unit_config; exclude such add-ons from the v1 list at the query layer.
+				ExcludeUnitConfig: true,
+			}
+
+			if params.Id != nil {
+				req.ID = &filter.FilterULID{FilterString: filter.FilterString{In: params.Id}}
+			}
+			if params.Key != nil {
+				req.Key = &filter.FilterString{In: params.Key}
+			}
+			if params.Currency != nil {
+				req.Currency = &filter.FilterString{In: params.Currency}
+			}
+
+			return req, nil
+		},
+		func(ctx context.Context, request ListAddonsRequest) (ListAddonsResponse, error) {
+			resp, err := h.service.ListAddons(ctx, request)
+			if err != nil {
+				return ListAddonsResponse{}, fmt.Errorf("failed to list add-ons: %w", err)
+			}
+
+			items := make([]api.Addon, 0, len(resp.Items))
+
+			for _, a := range resp.Items {
+				var item api.Addon
+
+				item, err = FromAddon(a)
+				if err != nil {
+					return ListAddonsResponse{}, fmt.Errorf("failed to cast add-on [namespace=%s key=%s]: %w", a.Namespace, a.Key, err)
+				}
+
+				items = append(items, item)
+			}
+
+			return ListAddonsResponse{
+				Items:      items,
+				Page:       resp.Page.PageNumber,
+				PageSize:   resp.Page.PageSize,
+				TotalCount: resp.TotalCount,
+			}, nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[ListAddonsResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("listAddons"),
+			httptransport.WithErrorEncoder(productcataloghttp.ValidationErrorEncoder(productcataloghttp.ResourceKindAddon)),
+		)...,
+	)
+}
+
+type (
+	CreateAddonRequest  = addon.CreateAddonInput
+	CreateAddonResponse = api.Addon
+	CreateAddonHandler  httptransport.Handler[CreateAddonRequest, CreateAddonResponse]
+)
+
+func (h *handler) CreateAddon() CreateAddonHandler {
+	return httptransport.NewHandler(
+		func(ctx context.Context, r *http.Request) (CreateAddonRequest, error) {
+			body := api.AddonCreate{}
+			if err := commonhttp.JSONRequestBodyDecoder(r, &body); err != nil {
+				return CreateAddonRequest{}, fmt.Errorf("failed to decode create add-on request: %w", err)
+			}
+
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return CreateAddonRequest{}, fmt.Errorf("failed to resolve namespace [namespace=%s]: %w", ns, err)
+			}
+
+			req, err := AsCreateAddonRequest(body, ns)
+			if err != nil {
+				return CreateAddonRequest{}, fmt.Errorf("failed to parse add-on request [namespace=%s key=%s]: %w", ns, body.Key, err)
+			}
+
+			req.NamespacedModel = models.NamespacedModel{
+				Namespace: ns,
+			}
+
+			req.IgnoreNonCriticalIssues = true
+
+			return req, nil
+		},
+		func(ctx context.Context, request CreateAddonRequest) (CreateAddonResponse, error) {
+			a, err := h.service.CreateAddon(ctx, request)
+			if err != nil {
+				return CreateAddonResponse{}, fmt.Errorf("failed to create add-on [namespace=%s key=%s]: %w", request.Namespace, request.Key, err)
+			}
+
+			return FromAddon(*a)
+		},
+		commonhttp.JSONResponseEncoderWithStatus[CreateAddonResponse](http.StatusCreated),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("createAddon"),
+			httptransport.WithErrorEncoder(productcataloghttp.ValidationErrorEncoder(productcataloghttp.ResourceKindAddon)),
+		)...,
+	)
+}
+
+type (
+	UpdateAddonRequest  = addon.UpdateAddonInput
+	UpdateAddonResponse = api.Addon
+	UpdateAddonHandler  httptransport.HandlerWithArgs[UpdateAddonRequest, UpdateAddonResponse, string]
+)
+
+func (h *handler) UpdateAddon() UpdateAddonHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, addonID string) (UpdateAddonRequest, error) {
+			body := api.AddonReplaceUpdate{}
+			if err := commonhttp.JSONRequestBodyDecoder(r, &body); err != nil {
+				return UpdateAddonRequest{}, fmt.Errorf("failed to decode update add-on request: %w", err)
+			}
+
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return UpdateAddonRequest{}, fmt.Errorf("failed to resolve namespace [namespace=%s]: %w", ns, err)
+			}
+
+			req, err := AsUpdateAddonRequest(body, ns, addonID)
+			if err != nil {
+				return UpdateAddonRequest{}, fmt.Errorf("failed to parse update add-on request [namespace=%s id=%s]: %w", ns, addonID, err)
+			}
+
+			req.NamespacedID = models.NamespacedID{
+				Namespace: ns,
+				ID:        addonID,
+			}
+
+			req.IgnoreNonCriticalIssues = true
+
+			req.RejectUnitConfig = true
+
+			return req, nil
+		},
+		func(ctx context.Context, request UpdateAddonRequest) (UpdateAddonResponse, error) {
+			a, err := h.service.UpdateAddon(ctx, request)
+			if err != nil {
+				return UpdateAddonResponse{}, fmt.Errorf("failed to update add-on [namespace=%s id=%s]: %w", request.Namespace, request.ID, err)
+			}
+
+			return FromAddon(*a)
+		},
+		commonhttp.JSONResponseEncoderWithStatus[UpdateAddonResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("updateAddon"),
+			httptransport.WithErrorEncoder(productcataloghttp.ValidationErrorEncoder(productcataloghttp.ResourceKindAddon)),
+		)...,
+	)
+}
+
+type (
+	DeleteAddonRequest  = addon.DeleteAddonInput
+	DeleteAddonResponse = interface{}
+	DeleteAddonHandler  httptransport.HandlerWithArgs[DeleteAddonRequest, DeleteAddonResponse, string]
+)
+
+func (h *handler) DeleteAddon() DeleteAddonHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, addonID string) (DeleteAddonRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return DeleteAddonRequest{}, fmt.Errorf("failed to resolve namespace [namespace=%s]: %w", ns, err)
+			}
+
+			return DeleteAddonRequest{
+				NamespacedID: models.NamespacedID{
+					Namespace: ns,
+					ID:        addonID,
+				},
+			}, nil
+		},
+		func(ctx context.Context, request DeleteAddonRequest) (DeleteAddonResponse, error) {
+			err := h.service.DeleteAddon(ctx, request)
+			if err != nil {
+				return nil, fmt.Errorf("failed to delete add-on [namespace=%s id=%s]: %w", request.Namespace, request.ID, err)
+			}
+
+			return nil, nil
+		},
+		commonhttp.EmptyResponseEncoder[DeleteAddonResponse](http.StatusNoContent),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("deleteAddon"),
+			httptransport.WithErrorEncoder(productcataloghttp.ValidationErrorEncoder(productcataloghttp.ResourceKindAddon)),
+		)...,
+	)
+}
+
+type (
+	GetAddonRequest       = addon.GetAddonInput
+	GetAddonRequestParams struct {
+		// AddonID or Key.
+		IDOrKey string
+
+		// Version is the version of the add-on.
+		// If not set the latest version is assumed.
+		Version int
+
+		// AllowLatest defines whether return the latest version regardless of its AddonStatus or with ActiveStatus only if
+		// Version is not set.
+		IncludeLatest bool
+	}
+	GetAddonResponse = api.Addon
+	GetAddonHandler  httptransport.HandlerWithArgs[GetAddonRequest, GetAddonResponse, GetAddonRequestParams]
+)
+
+func (h *handler) GetAddon() GetAddonHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, params GetAddonRequestParams) (GetAddonRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return GetAddonRequest{}, fmt.Errorf("failed to resolve namespace [namespace=%s]: %w", ns, err)
+			}
+
+			// Try to detect whether the IdOrKey is an ID in ULID format or Key.
+			idOrKey := ref.ParseIDOrKey(params.IDOrKey)
+
+			return GetAddonRequest{
+				NamespacedID: models.NamespacedID{
+					Namespace: ns,
+					ID:        idOrKey.ID,
+				},
+				Key:           idOrKey.Key,
+				Version:       params.Version,
+				IncludeLatest: params.IncludeLatest,
+			}, nil
+		},
+		func(ctx context.Context, request GetAddonRequest) (GetAddonResponse, error) {
+			a, err := h.service.GetAddon(ctx, request)
+			if err != nil {
+				return GetAddonResponse{}, fmt.Errorf("failed to get add-on [namespace=%s key=%s id=%s]: %w", request.Namespace, request.Key, request.ID, err)
+			}
+
+			if a.AsProductCatalogAddon().HasUnitConfig() {
+				return GetAddonResponse{}, productcatalog.ErrUnitConfigNotRepresentable
+			}
+
+			return FromAddon(*a)
+		},
+		commonhttp.JSONResponseEncoderWithStatus[GetAddonResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("getAddon"),
+			httptransport.WithErrorEncoder(productcataloghttp.ValidationErrorEncoder(productcataloghttp.ResourceKindAddon)),
+		)...,
+	)
+}
+
+type (
+	PublishAddonRequest  = addon.PublishAddonInput
+	PublishAddonResponse = api.Addon
+	PublishAddonHandler  httptransport.HandlerWithArgs[PublishAddonRequest, PublishAddonResponse, string]
+)
+
+func (h *handler) PublishAddon() PublishAddonHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, addonID string) (PublishAddonRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return PublishAddonRequest{}, fmt.Errorf("failed to resolve namespace [namespace=%s]: %w", ns, err)
+			}
+
+			// TODO(chrisgacsal): update api.Request in TypeSpec definition to allow setting EffectivePeriod
+
+			req := PublishAddonRequest{
+				NamespacedID: models.NamespacedID{
+					Namespace: ns,
+					ID:        addonID,
+				},
+				EffectivePeriod: productcatalog.EffectivePeriod{
+					EffectiveFrom: lo.ToPtr(clock.Now()),
+				},
+				RejectUnitConfig: true,
+			}
+
+			return req, nil
+		},
+		func(ctx context.Context, request PublishAddonRequest) (PublishAddonResponse, error) {
+			a, err := h.service.PublishAddon(ctx, request)
+			if err != nil {
+				return PublishAddonResponse{}, fmt.Errorf("failed to punlish add-on [namespace=%s id=%s]: %w", request.Namespace, request.ID, err)
+			}
+
+			return FromAddon(*a)
+		},
+		commonhttp.JSONResponseEncoderWithStatus[PublishAddonResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("publishAddon"),
+			httptransport.WithErrorEncoder(productcataloghttp.ValidationErrorEncoder(productcataloghttp.ResourceKindAddon)),
+		)...,
+	)
+}
+
+type (
+	ArchiveAddonRequest  = addon.ArchiveAddonInput
+	ArchiveAddonResponse = api.Addon
+	ArchiveAddonHandler  httptransport.HandlerWithArgs[ArchiveAddonRequest, ArchiveAddonResponse, string]
+)
+
+func (h *handler) ArchiveAddon() ArchiveAddonHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, addonID string) (ArchiveAddonRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return ArchiveAddonRequest{}, fmt.Errorf("failed to resolve namespace [namespace=%s]: %w", ns, err)
+			}
+
+			// TODO(chrisgacsal): update api.Request in TypeSpec definition to allow setting EffectivePeriod.To
+
+			req := ArchiveAddonRequest{
+				NamespacedID: models.NamespacedID{
+					Namespace: ns,
+					ID:        addonID,
+				},
+				EffectiveTo: clock.Now(),
+				// The v1 API cannot represent unit_config; reject archiving such an add-on.
+				RejectUnitConfig: true,
+			}
+
+			return req, nil
+		},
+		func(ctx context.Context, request ArchiveAddonRequest) (ArchiveAddonResponse, error) {
+			p, err := h.service.ArchiveAddon(ctx, request)
+			if err != nil {
+				return ArchiveAddonResponse{}, fmt.Errorf("failed to archive add-on [namespace=%s id=%s]: %w", request.Namespace, request.ID, err)
+			}
+
+			return FromAddon(*p)
+		},
+		commonhttp.JSONResponseEncoderWithStatus[ArchiveAddonResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("archiveAddon"),
+			httptransport.WithErrorEncoder(productcataloghttp.ValidationErrorEncoder(productcataloghttp.ResourceKindAddon)),
+		)...,
+	)
+}

openmeter/productcatalog/addon/httpdriver/driver.go

@@ -0,0 +1,55 @@
+package httpdriver
+
+import (
+	"context"
+	"errors"
+	"net/http"
+
+	"github.com/openmeterio/openmeter/openmeter/namespace/namespacedriver"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/addon"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type Handler interface {
+	AddonHandler
+}
+
+type AddonHandler interface {
+	ListAddons() ListAddonsHandler
+	CreateAddon() CreateAddonHandler
+	DeleteAddon() DeleteAddonHandler
+	GetAddon() GetAddonHandler
+	UpdateAddon() UpdateAddonHandler
+	PublishAddon() PublishAddonHandler
+	ArchiveAddon() ArchiveAddonHandler
+}
+
+var _ Handler = (*handler)(nil)
+
+type handler struct {
+	service          addon.Service
+	namespaceDecoder namespacedriver.NamespaceDecoder
+	options          []httptransport.HandlerOption
+}
+
+func (h *handler) resolveNamespace(ctx context.Context) (string, error) {
+	ns, ok := h.namespaceDecoder.GetNamespace(ctx)
+	if !ok {
+		return "", commonhttp.NewHTTPError(http.StatusInternalServerError, errors.New("internal server error"))
+	}
+
+	return ns, nil
+}
+
+func New(
+	namespaceDecoder namespacedriver.NamespaceDecoder,
+	service addon.Service,
+	options ...httptransport.HandlerOption,
+) Handler {
+	return &handler{
+		service:          service,
+		namespaceDecoder: namespaceDecoder,
+		options:          options,
+	}
+}

openmeter/productcatalog/addon/httpdriver/mapping.go

@@ -0,0 +1,113 @@
+package httpdriver
+
+import (
+	"fmt"
+
+	"github.com/invopop/gobl/currency"
+	"github.com/samber/lo"
+
+	"github.com/openmeterio/openmeter/api"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/addon"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/http"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+func FromAddon(a addon.Addon) (api.Addon, error) {
+	validationIssues, _ := a.AsProductCatalogAddon().ValidationErrors()
+
+	resp := api.Addon{
+		CreatedAt:        a.CreatedAt,
+		Currency:         a.Currency.String(),
+		DeletedAt:        a.DeletedAt,
+		Description:      a.Description,
+		InstanceType:     api.AddonInstanceType(a.InstanceType),
+		EffectiveFrom:    a.EffectiveFrom,
+		EffectiveTo:      a.EffectiveTo,
+		Id:               a.ID,
+		Key:              a.Key,
+		Metadata:         http.FromMetadata(a.Metadata),
+		Annotations:      http.FromAnnotations(a.Annotations),
+		Name:             a.Name,
+		UpdatedAt:        a.UpdatedAt,
+		Version:          a.Version,
+		ValidationErrors: http.FromValidationErrors(validationIssues),
+	}
+
+	resp.RateCards = make([]api.RateCard, 0, len(a.RateCards))
+	for _, rateCard := range a.RateCards.AsProductCatalogRateCards() {
+		rc, err := http.FromRateCard(rateCard)
+		if err != nil {
+			return resp, fmt.Errorf("failed to cast ratecard: %w", err)
+		}
+
+		resp.RateCards = append(resp.RateCards, rc)
+	}
+
+	switch a.Status() {
+	case productcatalog.AddonStatusDraft:
+		resp.Status = api.AddonStatusDraft
+	case productcatalog.AddonStatusActive:
+		resp.Status = api.AddonStatusActive
+	case productcatalog.AddonStatusArchived:
+		resp.Status = api.AddonStatusArchived
+	default:
+		return resp, fmt.Errorf("invalid add-on status: %s", a.Status())
+	}
+
+	return resp, nil
+}
+
+func AsCreateAddonRequest(a api.AddonCreate, namespace string) (CreateAddonRequest, error) {
+	var err error
+
+	req := CreateAddonRequest{
+		NamespacedModel: models.NamespacedModel{
+			Namespace: namespace,
+		},
+		Addon: productcatalog.Addon{
+			AddonMeta: productcatalog.AddonMeta{
+				Key:          a.Key,
+				Name:         a.Name,
+				Description:  a.Description,
+				InstanceType: productcatalog.AddonInstanceType(a.InstanceType),
+				Metadata:     lo.FromPtrOr(a.Metadata, nil),
+			},
+			RateCards: nil,
+		},
+	}
+
+	req.Currency = currency.Code(a.Currency)
+	if err = req.Currency.Validate(); err != nil {
+		return req, fmt.Errorf("invalid CurrencyCode: %w", err)
+	}
+
+	req.RateCards, err = http.AsRateCards(a.RateCards)
+	if err != nil {
+		return req, err
+	}
+
+	return req, nil
+}
+
+func AsUpdateAddonRequest(a api.AddonReplaceUpdate, namespace string, addonID string) (UpdateAddonRequest, error) {
+	req := UpdateAddonRequest{
+		NamespacedID: models.NamespacedID{
+			Namespace: namespace,
+			ID:        addonID,
+		},
+		Name:         lo.ToPtr(a.Name),
+		Description:  a.Description,
+		InstanceType: lo.ToPtr(productcatalog.AddonInstanceType(a.InstanceType)),
+		Metadata:     (*models.Metadata)(a.Metadata),
+	}
+
+	rateCards, err := http.AsRateCards(a.RateCards)
+	if err != nil {
+		return req, err
+	}
+
+	req.RateCards = &rateCards
+
+	return req, nil
+}

openmeter/productcatalog/addon/plan.go

@@ -0,0 +1,33 @@
+package addon
+
+import (
+	"errors"
+
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+var _ models.Validator = (*Addon)(nil)
+
+// Plan stores the Addon specific representation of planaddon.PlanAddon.
+type Plan struct {
+	models.NamespacedID
+	models.ManagedModel
+
+	productcatalog.PlanAddonMeta
+	productcatalog.Plan
+}
+
+func (p Plan) Validate() error {
+	var errs []error
+
+	if err := p.NamespacedID.Validate(); err != nil {
+		errs = append(errs, err)
+	}
+
+	if err := p.Plan.Validate(); err != nil {
+		errs = append(errs, err)
+	}
+
+	return models.NewNillableGenericValidationError(errors.Join(errs...))
+}

openmeter/productcatalog/addon/ratecard.go

@@ -0,0 +1,218 @@
+package addon
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+var (
+	_ models.Validator                      = (*RateCardManagedFields)(nil)
+	_ models.Equaler[RateCardManagedFields] = (*RateCardManagedFields)(nil)
+)
+
+type RateCardManagedFields struct {
+	models.ManagedModel
+	models.NamespacedID
+
+	// AddonID defines the Addon the RateCard assigned to.
+	AddonID string `json:"addonId"`
+}
+
+func (m RateCardManagedFields) Equal(v RateCardManagedFields) bool {
+	if m.Namespace != v.Namespace {
+		return false
+	}
+
+	if m.ID != v.ID {
+		return false
+	}
+
+	return m.AddonID == v.AddonID
+}
+
+func (m RateCardManagedFields) Validate() error {
+	var errs []error
+
+	if m.Namespace == "" {
+		errs = append(errs, errors.New("namespace must not be empty"))
+	}
+
+	if m.ID == "" {
+		errs = append(errs, errors.New("id must not be empty"))
+	}
+
+	return models.NewNillableGenericValidationError(errors.Join(errs...))
+}
+
+type ManagedRateCard interface {
+	ManagedFields() RateCardManagedFields
+}
+
+var (
+	_ ManagedRateCard         = (*RateCard)(nil)
+	_ productcatalog.RateCard = (*RateCard)(nil)
+)
+
+type RateCard struct {
+	productcatalog.RateCard
+	RateCardManagedFields
+}
+
+func (r *RateCard) ManagedFields() RateCardManagedFields {
+	return r.RateCardManagedFields
+}
+
+func (r *RateCard) Equal(v productcatalog.RateCard) bool {
+	if managed, ok := (v).(ManagedRateCard); ok {
+		if !r.RateCardManagedFields.Equal(managed.ManagedFields()) {
+			return false
+		}
+	}
+
+	if !r.RateCard.Equal(v) {
+		return false
+	}
+
+	return true
+}
+
+func (r *RateCard) Validate() error {
+	var errs []error
+
+	if err := r.RateCard.Validate(); err != nil {
+		errs = append(errs, err)
+	}
+
+	if err := r.RateCardManagedFields.Validate(); err != nil {
+		errs = append(errs, err)
+	}
+
+	if r.AddonID == "" {
+		errs = append(errs, errors.New("addonId must not be empty"))
+	}
+
+	return models.NewNillableGenericValidationError(errors.Join(errs...))
+}
+
+func (r *RateCard) MarshalJSON() ([]byte, error) {
+	serde := struct {
+		productcatalog.RateCardSerde
+		productcatalog.RateCard
+		RateCardManagedFields
+	}{
+		RateCardSerde: productcatalog.RateCardSerde{
+			Type: r.Type(),
+		},
+		RateCard:              r.RateCard,
+		RateCardManagedFields: r.RateCardManagedFields,
+	}
+
+	return json.Marshal(serde)
+}
+
+func (r *RateCard) UnmarshalJSON(b []byte) error {
+	var s productcatalog.RateCardSerde
+	err := json.Unmarshal(b, &s)
+	if err != nil {
+		return fmt.Errorf("failed to JSON deserialize RateCard type: %w", err)
+	}
+
+	serde := struct {
+		productcatalog.RateCard
+		RateCardManagedFields
+	}{
+		RateCardManagedFields: r.RateCardManagedFields,
+		RateCard:              r.RateCard,
+	}
+
+	switch s.Type {
+	case productcatalog.FlatFeeRateCardType:
+		serde.RateCard = &productcatalog.FlatFeeRateCard{}
+	case productcatalog.UsageBasedRateCardType:
+		serde.RateCard = &productcatalog.UsageBasedRateCard{}
+	default:
+		return fmt.Errorf("invalid RateCard type: %s", s.Type)
+	}
+
+	err = json.Unmarshal(b, &serde)
+	if err != nil {
+		return fmt.Errorf("failed to JSON deserialize UsageBasedRateCard: %w", err)
+	}
+
+	r.RateCardManagedFields = serde.RateCardManagedFields
+	r.RateCard = serde.RateCard
+
+	return nil
+}
+
+type RateCards []RateCard
+
+func (c RateCards) At(idx int) RateCard {
+	return c[idx]
+}
+
+func (c RateCards) AsProductCatalogRateCards() productcatalog.RateCards {
+	var rcs productcatalog.RateCards
+
+	for _, rc := range c {
+		rcs = append(rcs, rc.RateCard)
+	}
+
+	return rcs
+}
+
+func (c RateCards) SingleBillingCadence() bool {
+	return c.AsProductCatalogRateCards().SingleBillingCadence()
+}
+
+func (c RateCards) Equal(v RateCards) bool {
+	if len(c) != len(v) {
+		return false
+	}
+
+	leftSet := make(map[string]RateCard)
+	for _, rc := range c {
+		leftSet[rc.Key()] = rc
+	}
+
+	rightSet := make(map[string]RateCard)
+	for _, rc := range v {
+		rightSet[rc.Key()] = rc
+	}
+
+	if len(leftSet) != len(rightSet) {
+		return false
+	}
+
+	var visited int
+	for key, left := range leftSet {
+		right, ok := rightSet[key]
+		if !ok {
+			return false
+		}
+
+		if !left.Equal(&right) {
+			return false
+		}
+
+		visited++
+	}
+
+	return visited == len(rightSet)
+}
+
+func (c RateCards) Validate() error {
+	var errs []error
+
+	for _, rc := range c {
+		if err := rc.Validate(); err != nil {
+			errs = append(errs, err)
+		}
+	}
+
+	return models.NewNillableGenericValidationError(errors.Join(errs...))
+}

openmeter/productcatalog/addon/ratecard_test.go

@@ -0,0 +1,399 @@
+package addon
+
+import (
+	"encoding/json"
+	"testing"
+	"time"
+
+	decimal "github.com/alpacahq/alpacadecimal"
+	"github.com/samber/lo"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/pkg/datetime"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+func TestRateCard_JSON(t *testing.T) {
+	tests := []struct {
+		Name          string
+		RateCard      productcatalog.RateCard
+		ExpectedError bool
+	}{
+		{
+			Name: "FlatFee",
+			RateCard: &RateCard{
+				RateCardManagedFields: RateCardManagedFields{
+					ManagedModel: models.ManagedModel{
+						CreatedAt: time.Now().Add(-2 * time.Hour).UTC(),
+						UpdatedAt: time.Now().Add(-1 * time.Hour).UTC(),
+						DeletedAt: lo.ToPtr(time.Now().UTC()),
+					},
+					NamespacedID: models.NamespacedID{
+						Namespace: "namespace-1",
+						ID:        "01JDPHJMKJ8SNYTK0GK88VD0E9",
+					},
+					AddonID: "01JDPHJMKKT1S3XF47V2AGMA6J",
+				},
+				RateCard: &productcatalog.FlatFeeRateCard{
+					RateCardMeta: productcatalog.RateCardMeta{
+						Key:         "feature-1",
+						Name:        "RateCard 1",
+						Description: lo.ToPtr("RateCard 1"),
+						Metadata: map[string]string{
+							"key": "value",
+						},
+						FeatureKey: lo.ToPtr("feature-1"),
+						FeatureID:  lo.ToPtr("01JBP3SGZ20Y7VRVC351TDFXYZ"),
+						EntitlementTemplate: productcatalog.NewEntitlementTemplateFrom(
+							productcatalog.StaticEntitlementTemplate{
+								Metadata: map[string]string{
+									"key": "value",
+								},
+								Config: []byte(`{"key":"value"}`),
+							}),
+						TaxConfig: &productcatalog.TaxConfig{
+							Stripe: &productcatalog.StripeTaxConfig{
+								Code: "txcd_99999999",
+							},
+						},
+						Price: productcatalog.NewPriceFrom(productcatalog.FlatPrice{
+							Amount:      decimal.NewFromInt(1000),
+							PaymentTerm: productcatalog.InAdvancePaymentTerm,
+						}),
+					},
+					BillingCadence: lo.ToPtr(datetime.MustParseDuration(t, "P1M")),
+				},
+			},
+		},
+		{
+			Name: "UsageBased",
+			RateCard: &RateCard{
+				RateCardManagedFields: RateCardManagedFields{
+					ManagedModel: models.ManagedModel{
+						CreatedAt: time.Now().Add(-2 * time.Hour).UTC(),
+						UpdatedAt: time.Now().Add(-1 * time.Hour).UTC(),
+						DeletedAt: lo.ToPtr(time.Now().UTC()),
+					},
+					NamespacedID: models.NamespacedID{
+						Namespace: "namespace-2",
+						ID:        "01JDPHJMKKHSBYD60YR9D26EST",
+					},
+					AddonID: "01JDPHJMKKH4YDJTQY5F3EAHCF",
+				},
+				RateCard: &productcatalog.UsageBasedRateCard{
+					RateCardMeta: productcatalog.RateCardMeta{
+						Key:         "feature-2",
+						Name:        "RateCard 2",
+						Description: lo.ToPtr("RateCard 2"),
+						Metadata: map[string]string{
+							"key": "value",
+						},
+						FeatureKey: lo.ToPtr("feature-2"),
+						FeatureID:  lo.ToPtr("01JBP3SGZ20Y7VRVC351TDFXYZ"),
+						EntitlementTemplate: productcatalog.NewEntitlementTemplateFrom(
+							productcatalog.MeteredEntitlementTemplate{
+								Metadata: map[string]string{
+									"key": "value",
+								},
+								IsSoftLimit:             true,
+								IssueAfterReset:         lo.ToPtr(500.0),
+								IssueAfterResetPriority: lo.ToPtr[uint8](1),
+								PreserveOverageAtReset:  lo.ToPtr(true),
+								UsagePeriod:             datetime.MustParseDuration(t, "P1M"),
+							}),
+						TaxConfig: &productcatalog.TaxConfig{
+							Stripe: &productcatalog.StripeTaxConfig{
+								Code: "txcd_99999999",
+							},
+						},
+						Price: productcatalog.NewPriceFrom(
+							productcatalog.UnitPrice{
+								Amount: decimal.NewFromInt(1000),
+								Commitments: productcatalog.Commitments{
+									MinimumAmount: lo.ToPtr(decimal.NewFromInt(10)),
+									MaximumAmount: lo.ToPtr(decimal.NewFromInt(1000)),
+								},
+							}),
+						Discounts: productcatalog.Discounts{
+							Percentage: &productcatalog.PercentageDiscount{
+								Percentage: models.NewPercentage(10),
+							},
+							Usage: &productcatalog.UsageDiscount{
+								Quantity: decimal.NewFromInt(100),
+							},
+						},
+					},
+					BillingCadence: datetime.MustParseDuration(t, "P1M"),
+				},
+			},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.Name, func(t *testing.T) {
+			b, err := json.Marshal(&test.RateCard)
+			require.NoErrorf(t, err, "serializing RateCard must not fail")
+
+			t.Logf("Serialized RateCard: %s", string(b))
+
+			var rc *RateCard
+			err = json.Unmarshal(b, &rc)
+			require.NoErrorf(t, err, "deserializing RateCard must not fail")
+
+			assert.Equal(t, test.RateCard, rc)
+		})
+	}
+}
+
+func TestFlatFeeRateCard(t *testing.T) {
+	t.Run("Validate", func(t *testing.T) {
+		tests := []struct {
+			Name          string
+			RateCard      RateCard
+			ExpectedError bool
+		}{
+			{
+				Name: "valid",
+				RateCard: RateCard{
+					RateCardManagedFields: RateCardManagedFields{
+						ManagedModel: models.ManagedModel{
+							CreatedAt: time.Now().Add(-2 * time.Hour).UTC(),
+							UpdatedAt: time.Now().Add(-1 * time.Hour).UTC(),
+							DeletedAt: lo.ToPtr(time.Now().UTC()),
+						},
+						NamespacedID: models.NamespacedID{
+							Namespace: "namespace-1",
+							ID:        "01JDPHJMKKBARD45QV203H97CE",
+						},
+						AddonID: "01JDPHJMKK2WFF1D8AD5SYB2P1",
+					},
+					RateCard: &productcatalog.FlatFeeRateCard{
+						RateCardMeta: productcatalog.RateCardMeta{
+							Key:         "feat-1",
+							Name:        "Flat 1",
+							Description: lo.ToPtr("Flat 1"),
+							Metadata: map[string]string{
+								"name": "Flat 1",
+							},
+							FeatureKey: lo.ToPtr("feat-1"),
+							FeatureID:  lo.ToPtr("01JBP3SGZ20Y7VRVC351TDFXYZ"),
+							EntitlementTemplate: productcatalog.NewEntitlementTemplateFrom(
+								productcatalog.StaticEntitlementTemplate{
+									Metadata: map[string]string{
+										"name": "static-1",
+									},
+									Config: []byte(`"test"`),
+								}),
+							TaxConfig: &productcatalog.TaxConfig{
+								Stripe: &productcatalog.StripeTaxConfig{
+									Code: "txcd_99999999",
+								},
+							},
+							Price: productcatalog.NewPriceFrom(productcatalog.FlatPrice{
+								Amount:      decimal.NewFromInt(1000),
+								PaymentTerm: productcatalog.InArrearsPaymentTerm,
+							}),
+						},
+						BillingCadence: lo.ToPtr(datetime.MustParseDuration(t, "P1M")),
+					},
+				},
+				ExpectedError: false,
+			},
+			{
+				Name: "invalid",
+				RateCard: RateCard{
+					RateCardManagedFields: RateCardManagedFields{
+						ManagedModel: models.ManagedModel{
+							CreatedAt: time.Now().Add(-2 * time.Hour).UTC(),
+							UpdatedAt: time.Now().Add(-1 * time.Hour).UTC(),
+							DeletedAt: lo.ToPtr(time.Now().UTC()),
+						},
+						NamespacedID: models.NamespacedID{
+							Namespace: "namespace-2",
+							ID:        "01JDPHJMKK6T8QBKQQQWGCCXYT",
+						},
+						AddonID: "01JDPHJMKKZCTPZMD5SYDJENP3",
+					},
+					RateCard: &productcatalog.FlatFeeRateCard{
+						RateCardMeta: productcatalog.RateCardMeta{
+							Key:         "feat-2",
+							Name:        "Flat 2",
+							Description: lo.ToPtr("Flat 2"),
+							Metadata: map[string]string{
+								"name": "Flat 2",
+							},
+							FeatureKey: lo.ToPtr("feat-2"),
+							FeatureID:  lo.ToPtr("01JBP3SGZ2YTM6DVH2W318TPNH"),
+							EntitlementTemplate: productcatalog.NewEntitlementTemplateFrom(
+								productcatalog.StaticEntitlementTemplate{
+									Metadata: map[string]string{
+										"name": "static-1",
+									},
+									Config: []byte("invalid JSON"),
+								}),
+							TaxConfig: &productcatalog.TaxConfig{
+								Stripe: &productcatalog.StripeTaxConfig{
+									Code: "invalid_code",
+								},
+							},
+							Price: productcatalog.NewPriceFrom(
+								productcatalog.FlatPrice{
+									Amount:      decimal.NewFromInt(-1000),
+									PaymentTerm: "invalid",
+								}),
+						},
+						BillingCadence: lo.ToPtr(datetime.MustParseDuration(t, "P0M")),
+					},
+				},
+				ExpectedError: true,
+			},
+		}
+
+		for _, test := range tests {
+			t.Run(test.Name, func(t *testing.T) {
+				err := test.RateCard.Validate()
+
+				if test.ExpectedError {
+					assert.Error(t, err)
+				} else {
+					assert.NoError(t, err)
+				}
+			})
+		}
+	})
+}
+
+func TestUsageBasedRateCard(t *testing.T) {
+	t.Run("Validate", func(t *testing.T) {
+		tests := []struct {
+			Name          string
+			RateCard      RateCard
+			ExpectedError bool
+		}{
+			{
+				Name: "valid",
+				RateCard: RateCard{
+					RateCardManagedFields: RateCardManagedFields{
+						ManagedModel: models.ManagedModel{
+							CreatedAt: time.Now().Add(-2 * time.Hour).UTC(),
+							UpdatedAt: time.Now().Add(-1 * time.Hour).UTC(),
+							DeletedAt: lo.ToPtr(time.Now().UTC()),
+						},
+						NamespacedID: models.NamespacedID{
+							Namespace: "namespace-1",
+							ID:        "01JDPHJMKKK8MN7DNTEPS7BJ65",
+						},
+						AddonID: "01JDPHJMKK9J7Z45XRM4J3DS72",
+					},
+					RateCard: &productcatalog.UsageBasedRateCard{
+						RateCardMeta: productcatalog.RateCardMeta{
+							Key:         "feat-1",
+							Name:        "Usage 1",
+							Description: lo.ToPtr("Usage 1"),
+							Metadata: map[string]string{
+								"name": "usage-1",
+							},
+							FeatureKey: lo.ToPtr("feat-1"),
+							FeatureID:  lo.ToPtr("01JBP3SGZ20Y7VRVC351TDFXYZ"),
+							EntitlementTemplate: productcatalog.NewEntitlementTemplateFrom(
+								productcatalog.MeteredEntitlementTemplate{
+									Metadata: map[string]string{
+										"name": "Entitlement 1",
+									},
+									IsSoftLimit:             true,
+									IssueAfterReset:         lo.ToPtr(500.0),
+									IssueAfterResetPriority: lo.ToPtr[uint8](1),
+									PreserveOverageAtReset:  nil,
+									UsagePeriod:             datetime.MustParseDuration(t, "P1M"),
+								}),
+							TaxConfig: &productcatalog.TaxConfig{
+								Stripe: &productcatalog.StripeTaxConfig{
+									Code: "txcd_99999999",
+								},
+							},
+							Price: productcatalog.NewPriceFrom(
+								productcatalog.UnitPrice{
+									Amount: decimal.NewFromInt(1000),
+									Commitments: productcatalog.Commitments{
+										MinimumAmount: lo.ToPtr(decimal.NewFromInt(500)),
+										MaximumAmount: lo.ToPtr(decimal.NewFromInt(1500)),
+									},
+								}),
+						},
+						BillingCadence: datetime.MustParseDuration(t, "P1M"),
+					},
+				},
+				ExpectedError: false,
+			},
+			{
+				Name: "invalid",
+				RateCard: RateCard{
+					RateCardManagedFields: RateCardManagedFields{
+						ManagedModel: models.ManagedModel{
+							CreatedAt: time.Now().Add(-2 * time.Hour).UTC(),
+							UpdatedAt: time.Now().Add(-1 * time.Hour).UTC(),
+							DeletedAt: lo.ToPtr(time.Now().UTC()),
+						},
+						NamespacedID: models.NamespacedID{
+							Namespace: "namespace-2",
+							ID:        "01JDPHJMKK6RGN078EQEPHVJS2",
+						},
+						AddonID: "01JDPHJMKKBZFWS90VX5BFFKPE",
+					},
+					RateCard: &productcatalog.UsageBasedRateCard{
+						RateCardMeta: productcatalog.RateCardMeta{
+							Key:         "feat-2",
+							Name:        "Usage 2",
+							Description: lo.ToPtr("Usage 2"),
+							Metadata: map[string]string{
+								"name": "usage-2",
+							},
+							FeatureKey: lo.ToPtr("feat-2"),
+							FeatureID:  lo.ToPtr("01JBWYR0G2PYB9DVADKQXF8E0P"),
+							EntitlementTemplate: productcatalog.NewEntitlementTemplateFrom(
+								productcatalog.MeteredEntitlementTemplate{
+									Metadata: map[string]string{
+										"name": "Entitlement 1",
+									},
+									IsSoftLimit:             true,
+									IssueAfterReset:         lo.ToPtr(500.0),
+									IssueAfterResetPriority: lo.ToPtr[uint8](1),
+									PreserveOverageAtReset:  nil,
+									UsagePeriod:             datetime.MustParseDuration(t, "P1M"),
+								}),
+							TaxConfig: &productcatalog.TaxConfig{
+								Stripe: &productcatalog.StripeTaxConfig{
+									Code: "invalid_code",
+								},
+							},
+							Price: productcatalog.NewPriceFrom(
+								productcatalog.UnitPrice{
+									Amount: decimal.NewFromInt(-1000),
+									Commitments: productcatalog.Commitments{
+										MinimumAmount: lo.ToPtr(decimal.NewFromInt(1500)),
+										MaximumAmount: lo.ToPtr(decimal.NewFromInt(500)),
+									},
+								}),
+						},
+						BillingCadence: datetime.MustParseDuration(t, "P0M"),
+					},
+				},
+				ExpectedError: true,
+			},
+		}
+
+		for _, test := range tests {
+			t.Run(test.Name, func(t *testing.T) {
+				err := test.RateCard.Validate()
+
+				if test.ExpectedError {
+					assert.Error(t, err)
+				} else {
+					assert.NoError(t, err)
+				}
+			})
+		}
+	})
+}

openmeter/productcatalog/addon/repository.go

@@ -0,0 +1,20 @@
+package addon
+
+import (
+	"context"
+
+	"github.com/openmeterio/openmeter/pkg/framework/entutils"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+)
+
+// TODO: add bulk api
+
+type Repository interface {
+	entutils.TxCreator
+
+	ListAddons(ctx context.Context, params ListAddonsInput) (pagination.Result[Addon], error)
+	CreateAddon(ctx context.Context, params CreateAddonInput) (*Addon, error)
+	DeleteAddon(ctx context.Context, params DeleteAddonInput) error
+	GetAddon(ctx context.Context, params GetAddonInput) (*Addon, error)
+	UpdateAddon(ctx context.Context, params UpdateAddonInput) (*Addon, error)
+}

openmeter/productcatalog/addon/service.go

@@ -0,0 +1,468 @@
+package addon
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"slices"
+	"time"
+
+	"github.com/samber/lo"
+
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/pkg/clock"
+	"github.com/openmeterio/openmeter/pkg/filter"
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+	"github.com/openmeterio/openmeter/pkg/sortx"
+)
+
+const timeJitter = 30 * time.Second
+
+const (
+	OrderAsc  = sortx.OrderAsc
+	OrderDesc = sortx.OrderDesc
+)
+
+const (
+	OrderByID        OrderBy = "id"
+	OrderByKey       OrderBy = "key"
+	OrderByVersion   OrderBy = "version"
+	OrderByCreatedAt OrderBy = "created_at"
+	OrderByUpdatedAt OrderBy = "updated_at"
+	OrderByName      OrderBy = "name"
+)
+
+type OrderBy string
+
+func (f OrderBy) Values() []OrderBy {
+	return []OrderBy{
+		OrderByID,
+		OrderByKey,
+		OrderByVersion,
+		OrderByCreatedAt,
+		OrderByUpdatedAt,
+		OrderByName,
+	}
+}
+
+func (f OrderBy) Validate() error {
+	if !slices.Contains(f.Values(), f) {
+		return models.NewGenericValidationError(fmt.Errorf("invalid add-on order by: %s", f))
+	}
+
+	return nil
+}
+
+type Service interface {
+	ListAddons(ctx context.Context, params ListAddonsInput) (pagination.Result[Addon], error)
+	CreateAddon(ctx context.Context, params CreateAddonInput) (*Addon, error)
+	DeleteAddon(ctx context.Context, params DeleteAddonInput) error
+	GetAddon(ctx context.Context, params GetAddonInput) (*Addon, error)
+	UpdateAddon(ctx context.Context, params UpdateAddonInput) (*Addon, error)
+	PublishAddon(ctx context.Context, params PublishAddonInput) (*Addon, error)
+	ArchiveAddon(ctx context.Context, params ArchiveAddonInput) (*Addon, error)
+	NextAddon(ctx context.Context, params NextAddonInput) (*Addon, error)
+}
+
+var _ models.Validator = (*ListAddonsInput)(nil)
+
+type ListAddonsInput struct {
+	// Page is the pagination parameters.
+	// TODO: make it optional.
+	pagination.Page
+
+	// OrderBy is the field to order by.
+	OrderBy OrderBy
+
+	// Order is the order direction.
+	Order sortx.Order
+
+	// Namespaces is the list of namespaces to filter by.
+	Namespaces []string
+
+	// KeyVersions is the map of keys to versions to filter by.
+	KeyVersions map[string][]int
+
+	// IncludeDeleted defines whether to include deleted Addons.
+	IncludeDeleted bool
+
+	// Status filter
+	Status []productcatalog.AddonStatus
+
+	// Filters
+	ID       *filter.FilterULID
+	Key      *filter.FilterString
+	Name     *filter.FilterString
+	Currency *filter.FilterString
+
+	// ExcludeUnitConfig omits add-ons carrying a unit_config conversion on any of their rate cards.
+	ExcludeUnitConfig bool
+}
+
+func (i ListAddonsInput) Validate() error {
+	var errs []error
+
+	if i.ID != nil {
+		if err := i.ID.Validate(); err != nil {
+			errs = append(errs, err)
+		}
+	}
+	if i.Key != nil {
+		if err := i.Key.Validate(); err != nil {
+			errs = append(errs, err)
+		}
+	}
+	if i.Name != nil {
+		if err := i.Name.Validate(); err != nil {
+			errs = append(errs, err)
+		}
+	}
+	if i.Currency != nil {
+		if err := i.Currency.Validate(); err != nil {
+			errs = append(errs, err)
+		}
+	}
+
+	if i.OrderBy != "" {
+		if err := i.OrderBy.Validate(); err != nil {
+			errs = append(errs, err)
+		}
+	}
+
+	return models.NewNillableGenericValidationError(errors.Join(errs...))
+}
+
+type ListAddonsStatusFilter struct {
+	// Active signals that the active Addons should be returned.
+	Active bool
+
+	// Draft signals that the draft Addons should be returned.
+	Draft bool
+
+	// Archived signals that the archived Addons should be returned.
+	Archived bool
+}
+
+type inputOptions struct {
+	// ignoreNonCriticalIssues makes Validate() return errors with critical severity or higher.
+	// This allows creating resource with expected validation issues.
+	IgnoreNonCriticalIssues bool
+}
+
+var _ models.Validator = (*CreateAddonInput)(nil)
+
+type CreateAddonInput struct {
+	models.NamespacedModel
+	productcatalog.Addon
+
+	inputOptions
+}
+
+func (i CreateAddonInput) Validate() error {
+	var errs []error
+
+	if i.Namespace == "" {
+		errs = append(errs, productcatalog.ErrNamespaceEmpty)
+	}
+
+	if err := i.Addon.Validate(); err != nil {
+		errs = append(errs, fmt.Errorf("invalid add-on: %w", err))
+	}
+
+	issues, err := models.AsValidationIssues(errors.Join(errs...))
+	if err != nil {
+		return models.NewGenericValidationError(err)
+	}
+
+	if i.IgnoreNonCriticalIssues {
+		issues = issues.WithSeverityOrHigher(models.ErrorSeverityCritical)
+	}
+
+	return models.NewNillableGenericValidationError(issues.AsError())
+}
+
+var (
+	_ models.Validator      = (*UpdateAddonInput)(nil)
+	_ models.Equaler[Addon] = (*UpdateAddonInput)(nil)
+)
+
+type UpdateAddonInput struct {
+	models.NamespacedID
+
+	// EffectivePeriod
+	productcatalog.EffectivePeriod
+
+	// Name
+	Name *string `json:"name"`
+
+	// Description
+	Description *string `json:"description,omitempty"`
+
+	// Metadata
+	Metadata *models.Metadata `json:"metadata,omitempty"`
+
+	// Metadata
+	Annotations *models.Annotations `json:"annotations,omitempty"`
+
+	// InstanceType
+	InstanceType *productcatalog.AddonInstanceType `json:"instanceType,omitempty"`
+
+	// RateCards
+	RateCards *productcatalog.RateCards `json:"rateCards,omitempty"`
+
+	// RejectUnitConfig makes mutation validation reject an add-on that carries a unit_config
+	// conversion on any rate card. The v1 API cannot represent unit_config, and v1 update
+	// rewrites rate cards from a body that has no such field, so proceeding would silently
+	// drop the conversion. v1 handlers set this; v3 leaves it false.
+	RejectUnitConfig bool
+
+	inputOptions
+}
+
+func (i UpdateAddonInput) Equal(p Addon) bool {
+	if i.Namespace != p.Namespace {
+		return false
+	}
+
+	if i.ID != p.ID {
+		return false
+	}
+
+	if !i.EffectivePeriod.Equal(p.EffectivePeriod) {
+		return false
+	}
+
+	if i.Name != nil && *i.Name != p.Name {
+		return false
+	}
+
+	if i.Description != nil && lo.FromPtr(i.Description) != lo.FromPtr(p.Description) {
+		return false
+	}
+
+	if i.Metadata != nil && !i.Metadata.Equal(p.Metadata) {
+		return false
+	}
+
+	if i.InstanceType != nil && *i.InstanceType != p.InstanceType {
+		return false
+	}
+
+	if i.RateCards != nil && !i.RateCards.Equal(p.RateCards.AsProductCatalogRateCards()) {
+		return false
+	}
+
+	return true
+}
+
+func (i UpdateAddonInput) Validate() error {
+	var errs []error
+
+	if i.Namespace == "" {
+		errs = append(errs, productcatalog.ErrNamespaceEmpty)
+	}
+
+	if i.ID == "" {
+		errs = append(errs, productcatalog.ErrIDEmpty)
+	}
+
+	if i.Name != nil && *i.Name == "" {
+		errs = append(errs, productcatalog.ErrResourceNameEmpty)
+	}
+
+	if i.EffectiveFrom != nil || i.EffectiveTo != nil {
+		if err := i.EffectivePeriod.Validate(); err != nil {
+			errs = append(errs, fmt.Errorf("invalid EffectivePeriod: %w", err))
+		}
+	}
+
+	if i.InstanceType != nil {
+		if err := i.InstanceType.Validate(); err != nil {
+			errs = append(errs, err)
+		}
+	}
+
+	if i.RateCards != nil {
+		if err := i.RateCards.Validate(); err != nil {
+			errs = append(errs, err)
+		}
+	}
+
+	issues, err := models.AsValidationIssues(errors.Join(errs...))
+	if err != nil {
+		return models.NewGenericValidationError(err)
+	}
+
+	if i.IgnoreNonCriticalIssues {
+		issues = issues.WithSeverityOrHigher(models.ErrorSeverityCritical)
+	}
+
+	return models.NewNillableGenericValidationError(issues.AsError())
+}
+
+type ExpandFields struct {
+	PlanAddons bool `json:"plans,omitempty"`
+}
+
+type GetAddonInput struct {
+	models.NamespacedID
+
+	// Key is the unique key for Addon.
+	Key string `json:"key,omitempty"`
+
+	// Version is the version of the Addon.
+	// If not set the latest version is assumed.
+	Version int `json:"version,omitempty"`
+
+	// IncludeLatest defines whether return the latest version regardless of its AddonStatus or with ActiveStatus only if
+	// Version is not set.
+	IncludeLatest bool `json:"includeLatest,omitempty"`
+
+	Expand ExpandFields `json:"expand,omitempty"`
+}
+
+func (i GetAddonInput) Validate() error {
+	var errs []error
+
+	if i.Namespace == "" {
+		errs = append(errs, productcatalog.ErrNamespaceEmpty)
+	}
+
+	if i.ID == "" && i.Key == "" {
+		errs = append(errs, errors.New("either add-on id or key must be provided"))
+	}
+
+	return models.NewNillableGenericValidationError(errors.Join(errs...))
+}
+
+type DeleteAddonInput struct {
+	models.NamespacedID
+}
+
+func (i DeleteAddonInput) Validate() error {
+	var errs []error
+
+	if i.Namespace == "" {
+		errs = append(errs, productcatalog.ErrNamespaceEmpty)
+	}
+
+	if i.ID == "" {
+		errs = append(errs, productcatalog.ErrIDEmpty)
+	}
+
+	return models.NewNillableGenericValidationError(errors.Join(errs...))
+}
+
+type PublishAddonInput struct {
+	models.NamespacedID
+
+	// AddonEffectivePeriod
+	productcatalog.EffectivePeriod
+
+	// RejectUnitConfig rejects the operation when the target add-on carries a unit_config
+	// conversion. The v1 API cannot represent it, so v1 handlers set this; v3 leaves it false.
+	RejectUnitConfig bool
+}
+
+func (i PublishAddonInput) Validate() error {
+	var errs []error
+
+	if i.Namespace == "" {
+		errs = append(errs, productcatalog.ErrNamespaceEmpty)
+	}
+
+	if i.ID == "" {
+		errs = append(errs, productcatalog.ErrIDEmpty)
+	}
+
+	now := clock.Now()
+
+	from := lo.FromPtr(i.EffectiveFrom)
+
+	if from.IsZero() {
+		errs = append(errs, errors.New("invalid EffectiveFrom: must not be empty"))
+	}
+
+	if !from.IsZero() && from.Before(now.Add(-timeJitter)) {
+		errs = append(errs, errors.New("invalid EffectiveFrom: period start must not be in the past"))
+	}
+
+	to := lo.FromPtr(i.EffectiveTo)
+
+	if !to.IsZero() && from.IsZero() {
+		errs = append(errs, errors.New("invalid EffectiveFrom: must not be empty if EffectiveTo is also set"))
+	}
+
+	if !to.IsZero() && to.Before(now.Add(timeJitter)) {
+		errs = append(errs, errors.New("invalid EffectiveTo: period end must not be in the past"))
+	}
+
+	if !from.IsZero() && !to.IsZero() && from.After(to) {
+		errs = append(errs, errors.New("invalid EffectivePeriod: period start must not be later than period end"))
+	}
+
+	return errors.Join(errs...)
+}
+
+type ArchiveAddonInput struct {
+	// NamespacedID
+	models.NamespacedID
+
+	// EffectiveFrom defines the time from the Addon is going to be unpublished.
+	EffectiveTo time.Time `json:"effectiveTo,omitempty"`
+
+	// RejectUnitConfig rejects the operation when the target add-on carries a unit_config
+	// conversion. The v1 API cannot represent it, so v1 handlers set this; v3 leaves it false.
+	RejectUnitConfig bool
+}
+
+func (i ArchiveAddonInput) Validate() error {
+	var errs []error
+
+	if i.Namespace == "" {
+		errs = append(errs, productcatalog.ErrNamespaceEmpty)
+	}
+
+	if i.ID == "" {
+		errs = append(errs, productcatalog.ErrIDEmpty)
+	}
+
+	if i.EffectiveTo.IsZero() {
+		errs = append(errs, errors.New("invalid EffectiveTo: must not be empty"))
+	}
+
+	now := clock.Now()
+
+	if i.EffectiveTo.Before(now.Add(-timeJitter)) {
+		errs = append(errs, errors.New("invalid EffectiveTo: period end must not be in the past"))
+	}
+
+	return errors.Join(errs...)
+}
+
+type NextAddonInput struct {
+	// NamespacedID
+	models.NamespacedID
+
+	// Key is the unique key for Addon.
+	Key string `json:"key,omitempty"`
+
+	// Version is the version of the Addon.
+	// If not set the latest version is assumed.
+	Version int `json:"version,omitempty"`
+}
+
+func (i NextAddonInput) Validate() error {
+	var errs []error
+
+	if i.Namespace == "" {
+		errs = append(errs, errors.New("invalid Namespace: must not be empty"))
+	}
+
+	if i.ID == "" && i.Key == "" {
+		errs = append(errs, errors.New("invalid: either ID or Key pair must be provided"))
+	}
+
+	return errors.Join(errs...)
+}

openmeter/productcatalog/addon/service/addon.go

@@ -0,0 +1,685 @@
+package service
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sort"
+
+	"github.com/samber/lo"
+
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/addon"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/featureresolver"
+	"github.com/openmeterio/openmeter/pkg/clock"
+	"github.com/openmeterio/openmeter/pkg/filter"
+	"github.com/openmeterio/openmeter/pkg/framework/transaction"
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+)
+
+func (s service) ListAddons(ctx context.Context, params addon.ListAddonsInput) (pagination.Result[addon.Addon], error) {
+	fn := func(ctx context.Context) (pagination.Result[addon.Addon], error) {
+		if err := params.Validate(); err != nil {
+			return pagination.Result[addon.Addon]{}, fmt.Errorf("invalid list add-ons params: %w", err)
+		}
+
+		return s.adapter.ListAddons(ctx, params)
+	}
+
+	return fn(ctx)
+}
+
+// resolveTaxCodes ensures that each RateCard with a Stripe tax code in its TaxConfig
+// has a corresponding TaxCode entity in the namespace. If no matching TaxCode exists,
+// one is created. The RateCard's TaxConfig.TaxCodeID is then populated.
+func (s service) resolveTaxCodes(ctx context.Context, namespace string, rateCards *productcatalog.RateCards) error {
+	if rateCards == nil || len(*rateCards) == 0 {
+		return nil
+	}
+
+	for _, rc := range *rateCards {
+		meta := rc.AsMeta()
+		if meta.TaxConfig == nil {
+			continue
+		}
+
+		if err := productcatalog.ResolveTaxConfig(ctx, s.taxCode, namespace, meta.TaxConfig); err != nil {
+			return err
+		}
+
+		var rcNew productcatalog.RateCard
+
+		switch rc.Type() {
+		case productcatalog.FlatFeeRateCardType:
+			rcNew = &productcatalog.FlatFeeRateCard{
+				RateCardMeta:   meta,
+				BillingCadence: rc.GetBillingCadence(),
+			}
+		case productcatalog.UsageBasedRateCardType:
+			bc := rc.GetBillingCadence()
+			if bc == nil {
+				return fmt.Errorf("billing cadence is required for usage-based rate card")
+			}
+
+			rcNew = &productcatalog.UsageBasedRateCard{
+				RateCardMeta:   meta,
+				BillingCadence: *bc,
+			}
+		default:
+			return fmt.Errorf("unsupported RateCard type: %s", rc.Type())
+		}
+
+		if err := rc.Merge(rcNew); err != nil {
+			return fmt.Errorf("failed to merge RateCard: %w", err)
+		}
+	}
+
+	return nil
+}
+
+// addonVersions is a collection of add-ons versions (all of them have the same namespace key pair).
+type addonVersions []addon.Addon
+
+func (a addonVersions) Len() int {
+	return len(a)
+}
+
+func (a addonVersions) Less(i, j int) bool {
+	return a[i].Version < a[j].Version
+}
+
+func (a addonVersions) Swap(i, j int) {
+	a[i], a[j] = a[j], a[i]
+}
+
+// Sort sorts the add-ons by their versions.
+func (a addonVersions) Sort() {
+	sort.Sort(a)
+}
+
+// Latest returns add-on with the latest version regardless of its deleted status.
+func (a addonVersions) Latest() *addon.Addon {
+	if len(a) == 0 {
+		return nil
+	}
+
+	// Ensure the collection is sorted
+	a.Sort()
+
+	return &a[len(a)-1]
+}
+
+// HasDraft returns true if there is an active (non-deleted) add-on with draft status.
+func (a addonVersions) HasDraft() bool {
+	for _, aa := range a {
+		if aa.DeletedAt == nil && aa.Status() == productcatalog.AddonStatusDraft {
+			return true
+		}
+	}
+
+	return false
+}
+
+func (s service) getAddonVersions(ctx context.Context, namespace, key string) (addonVersions, error) {
+	versions, err := s.adapter.ListAddons(ctx, addon.ListAddonsInput{
+		OrderBy:        addon.OrderByVersion,
+		Order:          addon.OrderAsc,
+		Namespaces:     []string{namespace},
+		Key:            &filter.FilterString{In: &[]string{key}},
+		IncludeDeleted: true,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("failed to list versions of the add-on: %w", err)
+	}
+
+	return versions.Items, nil
+}
+
+func (s service) CreateAddon(ctx context.Context, params addon.CreateAddonInput) (*addon.Addon, error) {
+	fn := func(ctx context.Context) (*addon.Addon, error) {
+		if err := params.Validate(); err != nil {
+			return nil, fmt.Errorf("invalid create add-on params: %w", err)
+		}
+
+		logger := s.logger.With(
+			"operation", "create",
+			"namespace", params.Namespace,
+			"addon.key", params.Key,
+		)
+
+		// Check if there is already an Add-on with the same Key
+		versions, err := s.getAddonVersions(ctx, params.Namespace, params.Key)
+		if err != nil {
+			return nil, fmt.Errorf("failed to get add-on generation: %w", err)
+		}
+
+		// Return error if the add-on generation already has an active (non-deleted) add-on with draft status
+		// as there can only be single draft add-on at a time.
+		if versions.HasDraft() {
+			return nil, models.NewGenericValidationError(
+				fmt.Errorf("only a single draft version is allowed for add-on"),
+			)
+		}
+
+		// Override the version parameter with the next version calculated from the last available version.
+		params.Version = lo.FromPtr(versions.Latest()).Version + 1
+
+		logger.Debug("creating add-on")
+
+		if len(params.RateCards) > 0 {
+			if err = featureresolver.ResolveFeaturesForRateCards(ctx, s.featureResolver, params.Namespace, &params.RateCards); err != nil {
+				return nil, fmt.Errorf("failed to resolve features for ratecards in add-on [addon.key=%s]: %w", params.Key, err)
+			}
+
+			if err = s.resolveTaxCodes(ctx, params.Namespace, &params.RateCards); err != nil {
+				return nil, fmt.Errorf("failed to resolve tax codes for ratecards in add-on: %w", err)
+			}
+		}
+
+		aa, err := s.adapter.CreateAddon(ctx, params)
+		if err != nil {
+			return nil, fmt.Errorf("failed to create add-on: %w", err)
+		}
+
+		logger.With("addon.id", aa.ID).Debug("add-on created")
+
+		// Emit add-on created event
+		event := addon.NewAddonCreateEvent(ctx, aa)
+		if err = s.publisher.Publish(ctx, event); err != nil {
+			return nil, fmt.Errorf("failed to publish add-on created event: %w", err)
+		}
+
+		return aa, nil
+	}
+
+	return transaction.Run(ctx, s.adapter, fn)
+}
+
+func (s service) DeleteAddon(ctx context.Context, params addon.DeleteAddonInput) error {
+	fn := func(ctx context.Context) (interface{}, error) {
+		if err := params.Validate(); err != nil {
+			return nil, fmt.Errorf("invalid delete add-on params: %w", err)
+		}
+
+		logger := s.logger.With(
+			"operation", "delete",
+			"namespace", params.Namespace,
+			"addon.id", params.ID,
+		)
+
+		logger.Debug("deleting add-on")
+
+		// Get the add-on to check if it can be deleted
+		add, err := s.adapter.GetAddon(ctx, addon.GetAddonInput{
+			NamespacedID: models.NamespacedID{
+				Namespace: params.Namespace,
+				ID:        params.ID,
+			},
+			Expand: addon.ExpandFields{
+				PlanAddons: true,
+			},
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to get add-on: %w", err)
+		}
+
+		if add.DeletedAt != nil && add.DeletedAt.Before(clock.Now()) {
+			return nil, nil
+		}
+
+		if add.Plans == nil {
+			return nil, fmt.Errorf("cannot check whether add-on has plans enabled as plans were not dfetched for add-on [namespace=%s id=%s key=%s]",
+				add.Namespace, add.ID, add.Key)
+		}
+
+		if len(*add.Plans) > 0 {
+			return nil, models.NewGenericValidationError(
+				fmt.Errorf("failed to delete add-on [namespace=%s id=%s key=%s]: add-on has active assignments", add.Namespace, add.ID, add.Key),
+			)
+		}
+
+		// Run validations prior deleting add-on.
+		if err = add.AsProductCatalogAddon().ValidateWith(
+			productcatalog.ValidateAddonWithStatus(productcatalog.AddonStatusDraft, productcatalog.AddonStatusArchived),
+		); err != nil {
+			return nil, err
+		}
+
+		// Delete the add-on
+		err = s.adapter.DeleteAddon(ctx, params)
+		if err != nil {
+			return nil, fmt.Errorf("failed to delete add-on: %w", err)
+		}
+
+		logger.Debug("add-on deleted")
+
+		// Get the deleted add-on to emit the event
+		add, err = s.adapter.GetAddon(ctx, addon.GetAddonInput{
+			NamespacedID: models.NamespacedID{
+				Namespace: params.Namespace,
+				ID:        params.ID,
+			},
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to get deleted add-on: %w", err)
+		}
+
+		// Emit add-on deleted event
+		event := addon.NewAddonDeleteEvent(ctx, add)
+		if err = s.publisher.Publish(ctx, event); err != nil {
+			return nil, fmt.Errorf("failed to publish add-on deleted event: %w", err)
+		}
+
+		return nil, nil
+	}
+
+	_, err := transaction.Run(ctx, s.adapter, fn)
+
+	return err
+}
+
+func (s service) GetAddon(ctx context.Context, params addon.GetAddonInput) (*addon.Addon, error) {
+	fn := func(ctx context.Context) (*addon.Addon, error) {
+		if err := params.Validate(); err != nil {
+			return nil, fmt.Errorf("invalid get add-on params: %w", err)
+		}
+
+		logger := s.logger.With(
+			"operation", "get",
+			"namespace", params.Namespace,
+			"addon.id", params.ID,
+			"addon.key", params.Key,
+			"addon.version", params.Version,
+		)
+
+		logger.Debug("fetching add-on")
+
+		aa, err := s.adapter.GetAddon(ctx, params)
+		if err != nil {
+			// FIXME: not found error
+			return nil, fmt.Errorf("failed to get add-on: %w", err)
+		}
+
+		logger.Debug("add-on fetched")
+
+		return aa, nil
+	}
+
+	return fn(ctx)
+}
+
+func (s service) UpdateAddon(ctx context.Context, params addon.UpdateAddonInput) (*addon.Addon, error) {
+	fn := func(ctx context.Context) (*addon.Addon, error) {
+		if err := params.Validate(); err != nil {
+			return nil, fmt.Errorf("invalid update add-on params: %w", err)
+		}
+
+		logger := s.logger.With(
+			"operation", "update",
+			"namespace", params.Namespace,
+			"addon.id", params.ID,
+		)
+		logger.Debug("updating add-on")
+
+		if params.RateCards != nil && len(*params.RateCards) > 0 {
+			if err := featureresolver.ResolveFeaturesForRateCards(ctx, s.featureResolver, params.Namespace, params.RateCards); err != nil {
+				return nil, fmt.Errorf("failed to expand features for ratecards in add-on: %w", err)
+			}
+
+			if err := s.resolveTaxCodes(ctx, params.Namespace, params.RateCards); err != nil {
+				return nil, fmt.Errorf("failed to resolve tax codes for ratecards in add-on: %w", err)
+			}
+		}
+
+		add, err := s.adapter.GetAddon(ctx, addon.GetAddonInput{
+			NamespacedID: models.NamespacedID{
+				Namespace: params.Namespace,
+				ID:        params.ID,
+			},
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to get add-on: %w", err)
+		}
+
+		if params.RejectUnitConfig && add.AsProductCatalogAddon().HasUnitConfig() {
+			return nil, productcatalog.ErrUnitConfigNotRepresentable
+		}
+
+		// Run validations prior updating add-on.
+		if err = add.AsProductCatalogAddon().ValidateWith(
+			productcatalog.ValidateAddonWithStatus(productcatalog.AddonStatusDraft),
+		); err != nil {
+			return nil, err
+		}
+
+		logger.Debug("updating add-on")
+
+		// NOTE(chrisgacsal): we only allow updating the state of the add-on via Publish/Archive,
+		// therefore the EffectivePeriod attribute must be zeroed before updating the add-on.
+		params.EffectivePeriod = productcatalog.EffectivePeriod{}
+
+		add, err = s.adapter.UpdateAddon(ctx, params)
+		if err != nil {
+			return nil, fmt.Errorf("failed to udpate add-on: %w", err)
+		}
+
+		logger.Debug("add-on updated")
+
+		// Emit add-on updated event
+		event := addon.NewAddonUpdateEvent(ctx, add)
+		if err = s.publisher.Publish(ctx, event); err != nil {
+			return nil, fmt.Errorf("failed to publish add-on updated event: %w", err)
+		}
+
+		return add, nil
+	}
+
+	return transaction.Run(ctx, s.adapter, fn)
+}
+
+func (s service) PublishAddon(ctx context.Context, params addon.PublishAddonInput) (*addon.Addon, error) {
+	fn := func(ctx context.Context) (*addon.Addon, error) {
+		if err := params.Validate(); err != nil {
+			return nil, fmt.Errorf("invalid publish add-on params: %w", err)
+		}
+
+		logger := s.logger.With(
+			"operation", "publish",
+			"namespace", params.Namespace,
+			"addon.id", params.ID,
+		)
+
+		logger.Debug("publishing add-on")
+
+		add, err := s.adapter.GetAddon(ctx, addon.GetAddonInput{
+			NamespacedID: models.NamespacedID{
+				Namespace: params.Namespace,
+				ID:        params.ID,
+			},
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to get add-on: %w", err)
+		}
+
+		if add.DeletedAt != nil {
+			return nil, models.NewGenericValidationError(
+				fmt.Errorf("cannot publish a deleted add-on"),
+			)
+		}
+
+		if params.RejectUnitConfig && add.AsProductCatalogAddon().HasUnitConfig() {
+			return nil, productcatalog.ErrUnitConfigNotRepresentable
+		}
+
+		pa := add.AsProductCatalogAddon()
+
+		// Run validations prior publishing add-on.
+
+		var errs []error
+
+		if err = pa.Publishable(); err != nil {
+			errs = append(errs, fmt.Errorf("invalid add-on [id=%s key=%s version=%d]: %w",
+				add.ID, add.Key, add.Version, err),
+			)
+		}
+
+		// Validate plan with features
+		err = pa.ValidateWith(
+			productcatalog.ValidateAddonWithFeatures(ctx, s.featureResolver.WithNamespace(params.Namespace)),
+		)
+		if err != nil {
+			errs = append(errs, fmt.Errorf("invalid add-on [id=%s key=%s version=%d]: %w",
+				add.ID, add.Key, add.Version, err),
+			)
+		}
+
+		if err = errors.Join(errs...); err != nil {
+			return nil, models.NewGenericValidationError(err)
+		}
+
+		// Find and archive add-on version with addon.AddonStatusActive if there is one. Only perform lookup if
+		// the add-on to be published has higher version then 1 meaning that it has previous versions,
+		// otherwise skip this step.
+		if add.Version > 1 {
+			activeAddon, err := s.adapter.GetAddon(ctx, addon.GetAddonInput{
+				NamespacedID: models.NamespacedID{
+					Namespace: params.Namespace,
+				},
+				Key: add.Key,
+			})
+			if err != nil {
+				if !addon.IsNotFound(err) {
+					return nil, fmt.Errorf("failed to get add-on with active status: %w", err)
+				}
+			}
+
+			if activeAddon != nil && params.EffectiveFrom != nil {
+				_, err = s.ArchiveAddon(ctx, addon.ArchiveAddonInput{
+					NamespacedID: models.NamespacedID{
+						Namespace: activeAddon.Namespace,
+						ID:        activeAddon.ID,
+					},
+					EffectiveTo:      lo.FromPtr(params.EffectiveFrom),
+					RejectUnitConfig: params.RejectUnitConfig,
+				})
+				if err != nil {
+					return nil, fmt.Errorf("failed to archive add-on with active status: %w", err)
+				}
+			}
+		}
+
+		// Publish new add-on version
+
+		input := addon.UpdateAddonInput{
+			NamespacedID: params.NamespacedID,
+		}
+
+		if params.EffectiveFrom != nil {
+			input.EffectiveFrom = lo.ToPtr(params.EffectiveFrom.UTC())
+		}
+
+		if params.EffectiveTo != nil {
+			input.EffectiveTo = lo.ToPtr(params.EffectiveTo.UTC())
+		}
+
+		add, err = s.adapter.UpdateAddon(ctx, input)
+		if err != nil {
+			return nil, fmt.Errorf("failed to publish add-on: %w", err)
+		}
+
+		logger.Debug("add-on published")
+
+		// Emit add-on published event
+		event := addon.NewAddonPublishEvent(ctx, add)
+		if err := s.publisher.Publish(ctx, event); err != nil {
+			return nil, fmt.Errorf("failed to publish add-on published event: %w", err)
+		}
+
+		return add, nil
+	}
+
+	return transaction.Run(ctx, s.adapter, fn)
+}
+
+func (s service) ArchiveAddon(ctx context.Context, params addon.ArchiveAddonInput) (*addon.Addon, error) {
+	fn := func(ctx context.Context) (*addon.Addon, error) {
+		if err := params.Validate(); err != nil {
+			return nil, fmt.Errorf("invalid archive add-on params: %w", err)
+		}
+
+		logger := s.logger.With(
+			"operation", "archive",
+			"namespace", params.Namespace,
+			"addon.id", params.ID,
+		)
+
+		logger.Debug("archiving add-on")
+
+		add, err := s.adapter.GetAddon(ctx, addon.GetAddonInput{
+			NamespacedID: models.NamespacedID{
+				Namespace: params.Namespace,
+				ID:        params.ID,
+			},
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to get add-on: %w", err)
+		}
+
+		if add.DeletedAt != nil {
+			return nil, models.NewGenericValidationError(
+				fmt.Errorf("cannot archive a deleted add-on"),
+			)
+		}
+
+		if params.RejectUnitConfig && add.AsProductCatalogAddon().HasUnitConfig() {
+			return nil, productcatalog.ErrUnitConfigNotRepresentable
+		}
+
+		// Run validations prior archiving add-on.
+		if err = add.AsProductCatalogAddon().ValidateWith(
+			productcatalog.ValidateAddonWithStatus(productcatalog.AddonStatusActive),
+		); err != nil {
+			return nil, err
+		}
+
+		add, err = s.adapter.UpdateAddon(ctx, addon.UpdateAddonInput{
+			NamespacedID: models.NamespacedID{
+				Namespace: add.Namespace,
+				ID:        add.ID,
+			},
+			EffectivePeriod: productcatalog.EffectivePeriod{
+				EffectiveFrom: add.EffectiveFrom,
+				EffectiveTo:   lo.ToPtr(params.EffectiveTo.UTC()),
+			},
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to archive add-on: %w", err)
+		}
+
+		logger.Debug("add-on archived")
+
+		// Emit add-on archived event
+		event := addon.NewAddonArchiveEvent(ctx, add)
+		if err := s.publisher.Publish(ctx, event); err != nil {
+			return nil, fmt.Errorf("failed to publish add-on archived event: %w", err)
+		}
+
+		return add, nil
+	}
+
+	return transaction.Run(ctx, s.adapter, fn)
+}
+
+func (s service) NextAddon(ctx context.Context, params addon.NextAddonInput) (*addon.Addon, error) {
+	fn := func(ctx context.Context) (*addon.Addon, error) {
+		if err := params.Validate(); err != nil {
+			return nil, fmt.Errorf("invalid next version add-on params: %w", err)
+		}
+
+		logger := s.logger.With(
+			"operation", "next",
+			"namespace", params.Namespace,
+			"addon.id", params.ID,
+			"addon.key", params.Key,
+			"addon.version", params.Version,
+		)
+
+		logger.Debug("creating new version of an add-on")
+
+		// Fetch all version of an add-on to find the one to be used as source and also to calculate the next version number.
+		versions, err := s.getAddonVersions(ctx, params.Namespace, params.Key)
+		if err != nil {
+			return nil, fmt.Errorf("failed to get add-on generation: %w", err)
+		}
+
+		if versions.Len() == 0 {
+			return nil, models.NewGenericValidationError(
+				fmt.Errorf("no versions available for this add-on"),
+			)
+		}
+
+		// Generate source add-on filter from input parameters
+
+		// addonFilterFunc is a filter function which returns tuple where the first boolean means that
+		// there is a match while the second tells the caller to stop further invocations as there is an exact match.
+		type addonFilterFunc func(addon addon.Addon) (match bool, stop bool)
+
+		sourceAddonFilterFunc := func() addonFilterFunc {
+			switch {
+			case params.ID != "":
+				return func(a addon.Addon) (match bool, stop bool) {
+					if a.Namespace == params.Namespace && a.ID == params.ID {
+						return true, true
+					}
+
+					return false, false
+				}
+			case params.Key != "" && params.Version == 0:
+				return func(a addon.Addon) (match bool, stop bool) {
+					return a.Namespace == params.Namespace && a.Key == params.Key, false
+				}
+			default:
+				return func(a addon.Addon) (match bool, stop bool) {
+					if a.Namespace == params.Namespace && a.Key == params.Key && a.Version == params.Version {
+						return true, true
+					}
+
+					return false, false
+				}
+			}
+		}()
+
+		var sourceAddon *addon.Addon
+
+		nextVersion := 1
+		var match, stop bool
+		for _, addonItem := range versions {
+			if addonItem.DeletedAt == nil && addonItem.Status() == productcatalog.AddonStatusDraft {
+				return nil, models.NewGenericValidationError(
+					fmt.Errorf("only a single draft version is allowed for add-on"),
+				)
+			}
+
+			if !stop {
+				match, stop = sourceAddonFilterFunc(addonItem)
+				if match {
+					sourceAddon = &addonItem
+				}
+			}
+
+			if addonItem.Version >= nextVersion {
+				nextVersion = addonItem.Version + 1
+			}
+		}
+
+		if sourceAddon == nil {
+			return nil, models.NewGenericValidationError(
+				fmt.Errorf("no versions available for add-on to use as source for next draft version"),
+			)
+		}
+
+		nextAddon, err := s.adapter.CreateAddon(ctx, addon.CreateAddonInput{
+			NamespacedModel: models.NamespacedModel{
+				Namespace: sourceAddon.Namespace,
+			},
+			Addon: productcatalog.Addon{
+				AddonMeta: productcatalog.AddonMeta{
+					Key:         sourceAddon.Key,
+					Version:     nextVersion,
+					Name:        sourceAddon.Name,
+					Description: sourceAddon.Description,
+					Currency:    sourceAddon.Currency,
+				},
+				RateCards: sourceAddon.RateCards.AsProductCatalogRateCards(),
+			},
+		})
+		if err != nil {
+			return nil, fmt.Errorf("failed to create new version of a add-on: %w", err)
+		}
+
+		return nextAddon, nil
+	}
+
+	return transaction.Run(ctx, s.adapter, fn)
+}

openmeter/productcatalog/addon/service/service.go

@@ -0,0 +1,62 @@
+package service
+
+import (
+	"errors"
+	"log/slog"
+
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/addon"
+	"github.com/openmeterio/openmeter/openmeter/taxcode"
+	"github.com/openmeterio/openmeter/openmeter/watermill/eventbus"
+)
+
+type Config struct {
+	Adapter   addon.Repository
+	TaxCode   taxcode.Service
+	Logger    *slog.Logger
+	Publisher eventbus.Publisher
+
+	FeatureResolver productcatalog.FeatureResolver
+}
+
+func New(config Config) (addon.Service, error) {
+	if config.Adapter == nil {
+		return nil, errors.New("add-on adapter is required")
+	}
+
+	if config.FeatureResolver == nil {
+		return nil, errors.New("feature resolver is required")
+	}
+
+	if config.TaxCode == nil {
+		return nil, errors.New("tax code service is required")
+	}
+
+	if config.Logger == nil {
+		return nil, errors.New("logger is required")
+	}
+
+	if config.Publisher == nil {
+		return nil, errors.New("publisher is required")
+	}
+
+	return &service{
+		adapter:   config.Adapter,
+		taxCode:   config.TaxCode,
+		logger:    config.Logger,
+		publisher: config.Publisher,
+
+		featureResolver: config.FeatureResolver,
+	}, nil
+}
+
+var _ addon.Service = (*service)(nil)
+
+type service struct {
+	adapter   addon.Repository
+	taxCode   taxcode.Service
+	logger    *slog.Logger
+	publisher eventbus.Publisher
+
+	featureResolver productcatalog.FeatureResolver
+}

openmeter/productcatalog/addon/service/service_test.go

@@ -0,0 +1,610 @@
+package service_test
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	decimal "github.com/alpacahq/alpacadecimal"
+	"github.com/samber/lo"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/openmeterio/openmeter/openmeter/app"
+	"github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/addon"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	pctestutils "github.com/openmeterio/openmeter/openmeter/productcatalog/testutils"
+	"github.com/openmeterio/openmeter/openmeter/taxcode"
+	"github.com/openmeterio/openmeter/pkg/convert"
+	"github.com/openmeterio/openmeter/pkg/datetime"
+	"github.com/openmeterio/openmeter/pkg/filter"
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+)
+
+var MonthPeriod = datetime.ISODurationFromDuration(30 * 24 * time.Hour)
+
+func TestAddonService(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	env := pctestutils.NewTestEnv(t)
+	t.Cleanup(func() {
+		env.Close(t)
+	})
+
+	t.Run("Addon", func(t *testing.T) {
+		t.Run("Create", func(t *testing.T) {
+			// Get new namespace ID
+			namespace := pctestutils.NewTestNamespace(t)
+
+			// Setup meter repository
+			err := env.Meter.ReplaceMeters(ctx, pctestutils.NewTestMeters(t, namespace))
+			require.NoError(t, err, "replacing meters must not fail")
+
+			result, err := env.Meter.ListMeters(ctx, meter.ListMetersParams{
+				Page: pagination.Page{
+					PageSize:   1000,
+					PageNumber: 1,
+				},
+				Namespace: namespace,
+			})
+			require.NoErrorf(t, err, "listing meters must not fail")
+
+			meters := result.Items
+			require.NotEmptyf(t, meters, "list of Meters must not be empty")
+
+			// Set a feature for each meter
+			features := make([]feature.Feature, 0, len(meters))
+			for _, m := range meters {
+				input := pctestutils.NewTestFeatureFromMeter(t, &m)
+
+				feat, err := env.Feature.CreateFeature(ctx, input)
+				require.NoErrorf(t, err, "creating feature must not fail")
+				require.NotNil(t, feat, "feature must not be empty")
+
+				features = append(features, feat)
+			}
+
+			taxcode, err := env.TaxCode.CreateTaxCode(ctx, taxcode.CreateTaxCodeInput{
+				Namespace:   namespace,
+				Key:         "txcd_10000000",
+				Name:        "Test Tax Code",
+				Description: lo.ToPtr("Test Tax Code"),
+				AppMappings: []taxcode.TaxCodeAppMapping{
+					{
+						AppType: app.AppTypeStripe,
+						TaxCode: "txcd_10000000",
+					},
+				},
+				Metadata: models.Metadata{"name": "Test Tax Code"},
+			})
+			require.NoErrorf(t, err, "creating tax code must not fail")
+			require.NotNil(t, taxcode, "tax code must not be empty")
+
+			addonV1Input := pctestutils.NewTestAddon(t, namespace, productcatalog.RateCards{
+				&productcatalog.UsageBasedRateCard{
+					RateCardMeta: productcatalog.RateCardMeta{
+						Key:                 features[0].Key,
+						Name:                features[0].Name,
+						Description:         lo.ToPtr(features[0].Name),
+						Metadata:            models.Metadata{"name": features[0].Name},
+						FeatureKey:          nil,
+						FeatureID:           lo.ToPtr(features[0].ID),
+						EntitlementTemplate: productcatalog.NewEntitlementTemplateFrom(productcatalog.BooleanEntitlementTemplate{}),
+						TaxConfig: &productcatalog.TaxConfig{
+							Stripe: &productcatalog.StripeTaxConfig{
+								Code: "txcd_10000000",
+							},
+							TaxCodeID: lo.ToPtr(taxcode.ID),
+						},
+						Price: productcatalog.NewPriceFrom(productcatalog.TieredPrice{
+							Mode: productcatalog.VolumeTieredPrice,
+							Tiers: []productcatalog.PriceTier{
+								{
+									UpToAmount: lo.ToPtr(decimal.NewFromInt(1000)),
+									FlatPrice: &productcatalog.PriceTierFlatPrice{
+										Amount: decimal.NewFromInt(100),
+									},
+									UnitPrice: &productcatalog.PriceTierUnitPrice{
+										Amount: decimal.NewFromInt(50),
+									},
+								},
+								{
+									UpToAmount: nil,
+									FlatPrice: &productcatalog.PriceTierFlatPrice{
+										Amount: decimal.NewFromInt(5),
+									},
+									UnitPrice: &productcatalog.PriceTierUnitPrice{
+										Amount: decimal.NewFromInt(25),
+									},
+								},
+							},
+							Commitments: productcatalog.Commitments{
+								MinimumAmount: lo.ToPtr(decimal.NewFromInt(1000)),
+								MaximumAmount: nil,
+							},
+						}),
+					},
+					BillingCadence: MonthPeriod,
+				},
+			}...)
+
+			var addonV1 *addon.Addon
+
+			addonV1, err = env.Addon.CreateAddon(ctx, addonV1Input)
+			require.NoErrorf(t, err, "creating add-on must not fail")
+			require.NotNil(t, addonV1, "add-on must not be empty")
+
+			addon.AssertAddonCreateInputEqual(t, addonV1Input, *addonV1)
+
+			assert.Equalf(t, productcatalog.AddonStatusDraft, addonV1.Status(),
+				"add-on status mismatch: expected=%s, actual=%s", productcatalog.AddonStatusDraft, addonV1.Status())
+
+			t.Run("Get", func(t *testing.T) {
+				getAddon, err := env.Addon.GetAddon(ctx, addon.GetAddonInput{
+					NamespacedID: models.NamespacedID{
+						Namespace: addonV1Input.Namespace,
+					},
+					Key:           addonV1Input.Key,
+					IncludeLatest: true,
+				})
+				require.NoErrorf(t, err, "getting draft add-on must not fail")
+				require.NotNil(t, getAddon, "draft add-on must not be empty")
+
+				assert.Equalf(t, addonV1.ID, getAddon.ID,
+					"Plan ID mismatch: %s = %s", addonV1.ID, getAddon.ID)
+
+				assert.Equalf(t, addonV1.Key, getAddon.Key,
+					"Plan Key mismatch: %s = %s", addonV1.Key, getAddon.Key)
+
+				assert.Equalf(t, addonV1.Version, getAddon.Version,
+					"Plan Version mismatch: %d = %d", addonV1.Version, getAddon.Version)
+
+				assert.Equalf(t, productcatalog.AddonStatusDraft, getAddon.Status(),
+					"Plan Status mismatch: expected=%s, actual=%s", productcatalog.AddonStatusDraft, getAddon.Status())
+			})
+
+			t.Run("Update", func(t *testing.T) {
+				updateInput := addon.UpdateAddonInput{
+					NamespacedID: addonV1.NamespacedID,
+					RateCards: &productcatalog.RateCards{
+						&productcatalog.FlatFeeRateCard{
+							RateCardMeta: productcatalog.RateCardMeta{
+								Key:         features[0].Key,
+								Name:        features[0].Name,
+								Description: lo.ToPtr("RateCard 1"),
+								Metadata:    models.Metadata{"name": features[0].Name},
+								FeatureKey:  lo.ToPtr(features[0].Key),
+								FeatureID:   nil,
+								TaxConfig: &productcatalog.TaxConfig{
+									Stripe: &productcatalog.StripeTaxConfig{
+										Code: "txcd_10000000",
+									},
+									TaxCodeID: lo.ToPtr(taxcode.ID),
+								},
+								Price: productcatalog.NewPriceFrom(
+									productcatalog.FlatPrice{
+										Amount:      decimal.NewFromInt(0),
+										PaymentTerm: productcatalog.InArrearsPaymentTerm,
+									}),
+							},
+							BillingCadence: &MonthPeriod,
+						},
+						&productcatalog.UsageBasedRateCard{
+							RateCardMeta: productcatalog.RateCardMeta{
+								Key:                 features[1].Key,
+								Name:                features[1].Name,
+								Description:         lo.ToPtr(features[1].Name),
+								Metadata:            models.Metadata{"name": features[1].Name},
+								FeatureKey:          nil,
+								FeatureID:           lo.ToPtr(features[1].ID),
+								EntitlementTemplate: productcatalog.NewEntitlementTemplateFrom(productcatalog.BooleanEntitlementTemplate{}),
+								TaxConfig: &productcatalog.TaxConfig{
+									Stripe: &productcatalog.StripeTaxConfig{
+										Code: "txcd_10000000",
+									},
+									TaxCodeID: lo.ToPtr(taxcode.ID),
+								},
+								Price: productcatalog.NewPriceFrom(productcatalog.TieredPrice{
+									Mode: productcatalog.VolumeTieredPrice,
+									Tiers: []productcatalog.PriceTier{
+										{
+											UpToAmount: lo.ToPtr(decimal.NewFromInt(1000)),
+											FlatPrice: &productcatalog.PriceTierFlatPrice{
+												Amount: decimal.NewFromInt(100),
+											},
+											UnitPrice: &productcatalog.PriceTierUnitPrice{
+												Amount: decimal.NewFromInt(50),
+											},
+										},
+										{
+											UpToAmount: nil,
+											FlatPrice: &productcatalog.PriceTierFlatPrice{
+												Amount: decimal.NewFromInt(5),
+											},
+											UnitPrice: &productcatalog.PriceTierUnitPrice{
+												Amount: decimal.NewFromInt(25),
+											},
+										},
+									},
+									Commitments: productcatalog.Commitments{
+										MinimumAmount: lo.ToPtr(decimal.NewFromInt(1000)),
+										MaximumAmount: nil,
+									},
+								}),
+							},
+							BillingCadence: MonthPeriod,
+						},
+					},
+				}
+
+				updateInput.IgnoreNonCriticalIssues = true
+
+				updatedAddon, err := env.Addon.UpdateAddon(ctx, updateInput)
+				require.NoErrorf(t, err, "updating draft add-on must not fail")
+				require.NotNil(t, updatedAddon, "updated draft add-on must not be empty")
+
+				addon.AssertAddonUpdateInputEqual(t, updateInput, *updatedAddon)
+			})
+
+			var publishedAddonV1 *addon.Addon
+
+			t.Run("Publish", func(t *testing.T) {
+				publishAt := time.Now().Truncate(time.Microsecond)
+
+				publishInput := addon.PublishAddonInput{
+					NamespacedID: addonV1.NamespacedID,
+					EffectivePeriod: productcatalog.EffectivePeriod{
+						EffectiveFrom: &publishAt,
+						EffectiveTo:   nil,
+					},
+				}
+
+				publishedAddonV1, err = env.Addon.PublishAddon(ctx, publishInput)
+				require.NoErrorf(t, err, "publishing draft add-on must not fail")
+				require.NotNil(t, publishedAddonV1, "published add-on must not be empty")
+				require.NotNil(t, publishedAddonV1.EffectiveFrom, "EffectiveFrom for published add-on must not be empty")
+
+				assert.Equalf(t, publishAt, *publishedAddonV1.EffectiveFrom,
+					"EffectiveFrom for published add-on mismatch: expected=%s, actual=%s", publishAt, *publishedAddonV1.EffectiveFrom)
+
+				assert.Equalf(t, productcatalog.AddonStatusActive, publishedAddonV1.Status(),
+					"add-on Status mismatch: expected=%s, actual=%s", productcatalog.AddonStatusActive, publishedAddonV1.Status())
+
+				t.Run("Update", func(t *testing.T) {
+					updateInput := addon.UpdateAddonInput{
+						NamespacedID: addonV1.NamespacedID,
+						Name:         lo.ToPtr("Invalid Update"),
+					}
+
+					_, err = env.Addon.UpdateAddon(ctx, updateInput)
+					require.Errorf(t, err, "updating active add-on must fail")
+				})
+			})
+
+			var addonV2 *addon.Addon
+
+			t.Run("V2", func(t *testing.T) {
+				addonV2, err = env.Addon.CreateAddon(ctx, addonV1Input)
+				require.NoErrorf(t, err, "creating a new draft add-on from active must not fail")
+				require.NotNil(t, addonV2, "new draft add-on must not be empty")
+
+				assert.Equalf(t, publishedAddonV1.Version+1, addonV2.Version,
+					"new draft add-on must have higher version number")
+
+				assert.Equalf(t, productcatalog.AddonStatusDraft, addonV2.Status(),
+					"add-on Status mismatch: expected=%s, actual=%s", productcatalog.AddonStatusDraft, addonV2.Status())
+
+				t.Run("PublishUnaligned", func(t *testing.T) {
+					updateInput := addon.UpdateAddonInput{
+						NamespacedID: addonV2.NamespacedID,
+						RateCards: &productcatalog.RateCards{
+							&productcatalog.FlatFeeRateCard{
+								RateCardMeta: productcatalog.RateCardMeta{
+									Key:  "misaligned1",
+									Name: "Misaligned 1",
+									Price: productcatalog.NewPriceFrom(productcatalog.FlatPrice{
+										Amount:      decimal.NewFromInt(100),
+										PaymentTerm: productcatalog.DefaultPaymentTerm,
+									}),
+								},
+								BillingCadence: lo.ToPtr(datetime.MustParseDuration(t, "P1W")),
+							},
+							&productcatalog.FlatFeeRateCard{
+								RateCardMeta: productcatalog.RateCardMeta{
+									Key:  "misaligned2",
+									Name: "Misaligned 2",
+									Price: productcatalog.NewPriceFrom(productcatalog.FlatPrice{
+										Amount:      decimal.NewFromInt(10),
+										PaymentTerm: productcatalog.DefaultPaymentTerm,
+									}),
+								},
+								BillingCadence: lo.ToPtr(datetime.MustParseDuration(t, "P1M")),
+							},
+						},
+					}
+
+					_, err := env.Addon.UpdateAddon(ctx, updateInput)
+					require.NoError(t, err)
+
+					// Get the updated add-on
+					_, err = env.Addon.GetAddon(ctx, addon.GetAddonInput{
+						NamespacedID: addonV2.NamespacedID,
+					})
+					require.NoError(t, err)
+
+					// Let's try to publish the add-on
+					publishAt := time.Now().Truncate(time.Microsecond)
+
+					publishInput := addon.PublishAddonInput{
+						NamespacedID: addonV2.NamespacedID,
+						EffectivePeriod: productcatalog.EffectivePeriod{
+							EffectiveFrom: &publishAt,
+							EffectiveTo:   nil,
+						},
+					}
+
+					_, err = env.Addon.PublishAddon(ctx, publishInput)
+					require.Error(t, err, "publishing draft add-on with alignment issues must fail")
+
+					// Let's update the plan to fix the alignment issue
+					_, err = env.Addon.UpdateAddon(ctx, addon.UpdateAddonInput{
+						NamespacedID: addonV2.NamespacedID,
+						RateCards:    lo.ToPtr(publishedAddonV1.RateCards.AsProductCatalogRateCards()),
+					})
+					require.NoError(t, err)
+				})
+
+				t.Run("Publish", func(t *testing.T) {
+					publishAt := time.Now().Truncate(time.Microsecond)
+
+					publishInput := addon.PublishAddonInput{
+						NamespacedID: addonV2.NamespacedID,
+						EffectivePeriod: productcatalog.EffectivePeriod{
+							EffectiveFrom: &publishAt,
+							EffectiveTo:   nil,
+						},
+					}
+
+					publishedAddonV2, err := env.Addon.PublishAddon(ctx, publishInput)
+					require.NoErrorf(t, err, "publishing draft add-on must not fail")
+					require.NotNil(t, publishedAddonV2, "published add-on must not be empty")
+					require.NotNil(t, publishedAddonV2.EffectiveFrom, "EffectiveFrom for published add-on must not be empty")
+
+					assert.Equalf(t, publishAt, *publishedAddonV2.EffectiveFrom,
+						"EffectiveFrom for published add-on mismatch: expected=%s, actual=%s", publishAt, *publishedAddonV2.EffectiveFrom)
+
+					assert.Equalf(t, productcatalog.AddonStatusActive, publishedAddonV2.Status(),
+						"add-on Status mismatch: expected=%s, actual=%s", productcatalog.AddonStatusActive, publishedAddonV2.Status())
+
+					getAddonV1, err := env.Addon.GetAddon(ctx, addon.GetAddonInput{
+						NamespacedID: publishedAddonV1.NamespacedID,
+					})
+					require.NoErrorf(t, err, "getting previous add-on version must not fail")
+					require.NotNil(t, getAddonV1, "previous add version must not be empty")
+
+					assert.Equalf(t, productcatalog.AddonStatusArchived, getAddonV1.Status(),
+						"add Status mismatch: expected=%s, actual=%s", productcatalog.AddonStatusArchived, getAddonV1.Status())
+
+					t.Run("Archive", func(t *testing.T) {
+						archiveAt := time.Now().Truncate(time.Microsecond)
+
+						archiveInput := addon.ArchiveAddonInput{
+							NamespacedID: addonV2.NamespacedID,
+							EffectiveTo:  archiveAt,
+						}
+
+						archivedAddonV2, err := env.Addon.ArchiveAddon(ctx, archiveInput)
+						require.NoErrorf(t, err, "archiving add-on must not fail")
+						require.NotNil(t, archivedAddonV2, "archived add-on must not be empty")
+						require.NotNil(t, archivedAddonV2.EffectiveTo, "EffectiveFrom for archived add-on must not be empty")
+
+						assert.Equalf(t, archiveAt, *archivedAddonV2.EffectiveTo,
+							"EffectiveTo for published add-on mismatch: expected=%s, actual=%s", archiveAt, *archivedAddonV2.EffectiveTo)
+
+						assert.Equalf(t, productcatalog.AddonStatusArchived, archivedAddonV2.Status(),
+							"Status mismatch for archived add-on: expected=%s, actual=%s", productcatalog.AddonStatusArchived, archivedAddonV2.Status())
+					})
+				})
+
+				t.Run("Delete", func(t *testing.T) {
+					deleteInput := addon.DeleteAddonInput{
+						NamespacedID: addonV2.NamespacedID,
+					}
+
+					err = env.Addon.DeleteAddon(ctx, deleteInput)
+					require.NoErrorf(t, err, "deleting add-on must not fail")
+
+					deletedAddonV2, err := env.Addon.GetAddon(ctx, addon.GetAddonInput{
+						NamespacedID: addonV2.NamespacedID,
+					})
+					require.NoErrorf(t, err, "getting deleted add-on version must not fail")
+					require.NotNil(t, deletedAddonV2, "deleted add-on version must not be empty")
+
+					assert.NotNilf(t, deletedAddonV2.DeletedAt, "deletedAt must not be empty")
+
+					err = env.Addon.DeleteAddon(ctx, deleteInput)
+					require.NoErrorf(t, err, "deleting add-on must not fail")
+
+					deletedAddonV2Next, err := env.Addon.GetAddon(ctx, addon.GetAddonInput{
+						NamespacedID: addonV2.NamespacedID,
+					})
+					require.NoErrorf(t, err, "getting deleted add-on version must not fail")
+					require.NotNil(t, deletedAddonV2Next, "deleted add-on version must not be empty")
+
+					assert.Truef(t, deletedAddonV2.DeletedAt.Equal(*deletedAddonV2Next.DeletedAt), "deletedAt field must not be updated")
+				})
+			})
+		})
+	})
+}
+
+func TestAddonService_List(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	env := pctestutils.NewTestEnv(t)
+	t.Cleanup(func() {
+		env.Close(t)
+	})
+
+	namespace := pctestutils.NewTestNamespace(t)
+
+	// Create some addons for testing
+	addonCount := 5
+	addons := make([]*addon.Addon, 0, addonCount)
+	for i := range addonCount {
+		addonInput := pctestutils.NewTestAddon(t, namespace, &productcatalog.FlatFeeRateCard{
+			RateCardMeta: productcatalog.RateCardMeta{
+				Key:  fmt.Sprintf("rc-%d", i),
+				Name: fmt.Sprintf("RateCard %d", i),
+				Price: productcatalog.NewPriceFrom(productcatalog.FlatPrice{
+					Amount:      decimal.NewFromInt(100),
+					PaymentTerm: productcatalog.InAdvancePaymentTerm,
+				}),
+			},
+		})
+		addonInput.Key = fmt.Sprintf("addon-%d", i)
+		addonInput.Name = fmt.Sprintf("Addon %d", i)
+		if i%2 == 0 {
+			addonInput.Currency = "USD"
+		} else {
+			addonInput.Currency = "EUR"
+		}
+
+		a, err := env.Addon.CreateAddon(ctx, addonInput)
+		require.NoError(t, err)
+		addons = append(addons, a)
+	}
+
+	testCases := []struct {
+		name     string
+		input    addon.ListAddonsInput
+		validate func(t *testing.T, res pagination.Result[addon.Addon])
+	}{
+		{
+			name: "ListAll",
+			input: addon.ListAddonsInput{
+				Namespaces: []string{namespace},
+				Page: pagination.Page{
+					PageSize:   10,
+					PageNumber: 1,
+				},
+			},
+			validate: func(t *testing.T, res pagination.Result[addon.Addon]) {
+				assert.Len(t, res.Items, addonCount)
+			},
+		},
+		{
+			name: "FilterByID",
+			input: addon.ListAddonsInput{
+				Namespaces: []string{namespace},
+				ID: &filter.FilterULID{
+					FilterString: filter.FilterString{
+						Eq: convert.ToPointer(addons[0].ID),
+					},
+				},
+				Page: pagination.Page{
+					PageSize:   10,
+					PageNumber: 1,
+				},
+			},
+			validate: func(t *testing.T, res pagination.Result[addon.Addon]) {
+				assert.Len(t, res.Items, 1)
+				assert.Equal(t, addons[0].ID, res.Items[0].ID)
+			},
+		},
+		{
+			name: "FilterByKey",
+			input: addon.ListAddonsInput{
+				Namespaces: []string{namespace},
+				Key: &filter.FilterString{
+					Eq: convert.ToPointer(addons[1].Key),
+				},
+				Page: pagination.Page{
+					PageSize:   10,
+					PageNumber: 1,
+				},
+			},
+			validate: func(t *testing.T, res pagination.Result[addon.Addon]) {
+				assert.Len(t, res.Items, 1)
+				assert.Equal(t, addons[1].Key, res.Items[0].Key)
+			},
+		},
+		{
+			name: "FilterByName",
+			input: addon.ListAddonsInput{
+				Namespaces: []string{namespace},
+				Name: &filter.FilterString{
+					Contains: convert.ToPointer("Addon 2"),
+				},
+				Page: pagination.Page{
+					PageSize:   10,
+					PageNumber: 1,
+				},
+			},
+			validate: func(t *testing.T, res pagination.Result[addon.Addon]) {
+				assert.Len(t, res.Items, 1)
+				assert.Equal(t, "Addon 2", res.Items[0].Name)
+			},
+		},
+		{
+			name: "FilterByCurrency",
+			input: addon.ListAddonsInput{
+				Namespaces: []string{namespace},
+				Currency: &filter.FilterString{
+					Eq: convert.ToPointer("EUR"),
+				},
+				Page: pagination.Page{
+					PageSize:   10,
+					PageNumber: 1,
+				},
+			},
+			validate: func(t *testing.T, res pagination.Result[addon.Addon]) {
+				assert.Len(t, res.Items, 2)
+			},
+		},
+		{
+			name: "FilterByStatus",
+			input: addon.ListAddonsInput{
+				Namespaces: []string{namespace},
+				Status:     []productcatalog.AddonStatus{productcatalog.AddonStatusDraft},
+				Page: pagination.Page{
+					PageSize:   10,
+					PageNumber: 1,
+				},
+			},
+			validate: func(t *testing.T, res pagination.Result[addon.Addon]) {
+				assert.Len(t, res.Items, addonCount)
+			},
+		},
+		{
+			name: "SortByNameDesc",
+			input: addon.ListAddonsInput{
+				Namespaces: []string{namespace},
+				OrderBy:    addon.OrderByName,
+				Order:      addon.OrderDesc,
+				Page: pagination.Page{
+					PageSize:   10,
+					PageNumber: 1,
+				},
+			},
+			validate: func(t *testing.T, res pagination.Result[addon.Addon]) {
+				assert.Len(t, res.Items, addonCount)
+				assert.Equal(t, "Addon 4", res.Items[0].Name)
+			},
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			res, err := env.Addon.ListAddons(ctx, tc.input)
+			require.NoError(t, err)
+			tc.validate(t, res)
+		})
+	}
+}

openmeter/productcatalog/addon/service/taxcode_test.go

@@ -0,0 +1,899 @@
+package service_test
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	decimal "github.com/alpacahq/alpacadecimal"
+	"github.com/samber/lo"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/openmeterio/openmeter/openmeter/app"
+	"github.com/openmeterio/openmeter/openmeter/ent/db/addonratecard"
+	"github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/addon"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/planaddon"
+	pctestutils "github.com/openmeterio/openmeter/openmeter/productcatalog/testutils"
+	"github.com/openmeterio/openmeter/openmeter/taxcode"
+	taxcodetestutils "github.com/openmeterio/openmeter/openmeter/taxcode/testutils"
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+)
+
+func newTestAddonFlatRateCard(feat feature.Feature, tc *productcatalog.TaxConfig) productcatalog.RateCard {
+	return &productcatalog.FlatFeeRateCard{
+		RateCardMeta: productcatalog.RateCardMeta{
+			Key:        feat.Key,
+			Name:       feat.Name,
+			FeatureKey: lo.ToPtr(feat.Key),
+			FeatureID:  lo.ToPtr(feat.ID),
+			TaxConfig:  tc,
+			Price: productcatalog.NewPriceFrom(productcatalog.FlatPrice{
+				Amount:      decimal.NewFromInt(100),
+				PaymentTerm: productcatalog.InArrearsPaymentTerm,
+			}),
+		},
+		BillingCadence: &MonthPeriod,
+	}
+}
+
+func newTestAddonInput(t *testing.T, namespace string, rcs ...productcatalog.RateCard) addon.CreateAddonInput {
+	t.Helper()
+	return pctestutils.NewTestAddon(t, namespace, rcs...)
+}
+
+func getFirstAddonRCTaxConfig(t *testing.T, a *addon.Addon) *productcatalog.TaxConfig {
+	t.Helper()
+	require.NotEmpty(t, a.RateCards)
+	return a.RateCards[0].AsMeta().TaxConfig
+}
+
+func findAddonTaxCodeByStripeCode(t *testing.T, ctx context.Context, svc taxcode.Service, namespace string, stripeCode string) (taxcode.TaxCode, error) {
+	t.Helper()
+	return svc.GetTaxCodeByAppMapping(ctx, taxcode.GetTaxCodeByAppMappingInput{
+		Namespace: namespace,
+		AppType:   app.AppTypeStripe,
+		TaxCode:   stripeCode,
+	})
+}
+
+// assertAddonRCDBCols queries the AddonRateCard row directly from the database and asserts the
+// dedicated tax_code_id and tax_behavior columns match the expected values.
+func assertAddonRCDBCols(t *testing.T, ctx context.Context, env *pctestutils.TestEnv, addonID string, rcKey string, wantTaxCodeID *string, wantBehavior *productcatalog.TaxBehavior) {
+	t.Helper()
+	row, err := env.Client.AddonRateCard.Query().
+		Where(
+			addonratecard.AddonID(addonID),
+			addonratecard.Key(rcKey),
+			addonratecard.DeletedAtIsNil(),
+		).
+		Only(ctx)
+	require.NoError(t, err, "direct DB read of AddonRateCard must succeed")
+	assert.Equal(t, wantTaxCodeID, row.TaxCodeID, "tax_code_id column mismatch")
+	assert.Equal(t, wantBehavior, row.TaxBehavior, "tax_behavior column mismatch")
+}
+
+func TestAddonTaxCodeDualWrite(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	env := pctestutils.NewTestEnv(t)
+	t.Cleanup(func() {
+		env.Close(t)
+	})
+
+	namespace := pctestutils.NewTestNamespace(t)
+
+	// Setup meters and features
+	err := env.Meter.ReplaceMeters(ctx, pctestutils.NewTestMeters(t, namespace))
+	require.NoError(t, err)
+
+	result, err := env.Meter.ListMeters(ctx, meter.ListMetersParams{
+		Page: pagination.Page{
+			PageSize:   1000,
+			PageNumber: 1,
+		},
+		Namespace: namespace,
+	})
+	require.NoError(t, err)
+	require.NotEmpty(t, result.Items)
+
+	features := make([]feature.Feature, 0, len(result.Items))
+	for _, m := range result.Items {
+		feat, err := env.Feature.CreateFeature(ctx, pctestutils.NewTestFeatureFromMeter(t, &m))
+		require.NoError(t, err)
+		features = append(features, feat)
+	}
+
+	t.Run("Create", func(t *testing.T) {
+		t.Run("NoTaxConfig", func(t *testing.T) {
+			input := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], nil))
+			input.Key = "addon-no-tax-config"
+			input.Name = "No Tax Config"
+
+			a, err := env.Addon.CreateAddon(ctx, input)
+			require.NoError(t, err)
+
+			tc := getFirstAddonRCTaxConfig(t, a)
+			assert.Nil(t, tc, "TaxConfig should be nil")
+
+			assertAddonRCDBCols(t, ctx, env, a.ID, features[0].Key, nil, nil)
+		})
+
+		t.Run("StripeCodeOnly", func(t *testing.T) {
+			input := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], &productcatalog.TaxConfig{
+				Stripe: &productcatalog.StripeTaxConfig{
+					Code: "txcd_10000001",
+				},
+			}))
+			input.Key = "addon-stripe-only"
+			input.Name = "Stripe Only"
+
+			a, err := env.Addon.CreateAddon(ctx, input)
+			require.NoError(t, err)
+
+			tc := getFirstAddonRCTaxConfig(t, a)
+			require.NotNil(t, tc)
+
+			// Stripe code preserved
+			require.NotNil(t, tc.Stripe)
+			assert.Equal(t, "txcd_10000001", tc.Stripe.Code)
+
+			// TaxCodeID should be set
+			require.NotNil(t, tc.TaxCodeID, "TaxCodeID must be populated after resolution")
+
+			// Verify TaxCode entity exists
+			tcEntity, err := findAddonTaxCodeByStripeCode(t, ctx, env.TaxCode, namespace, "txcd_10000001")
+			require.NoError(t, err)
+			assert.Equal(t, *tc.TaxCodeID, tcEntity.ID)
+			assert.Equal(t, namespace, tcEntity.Namespace)
+
+			assertAddonRCDBCols(t, ctx, env, a.ID, features[0].Key, lo.ToPtr(tcEntity.ID), nil)
+		})
+
+		t.Run("StripeCodeAndBehavior", func(t *testing.T) {
+			input := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], &productcatalog.TaxConfig{
+				Behavior: lo.ToPtr(productcatalog.ExclusiveTaxBehavior),
+				Stripe: &productcatalog.StripeTaxConfig{
+					Code: "txcd_20000001",
+				},
+			}))
+			input.Key = "addon-stripe-and-behavior"
+			input.Name = "Stripe and Behavior"
+
+			a, err := env.Addon.CreateAddon(ctx, input)
+			require.NoError(t, err)
+
+			tc := getFirstAddonRCTaxConfig(t, a)
+			require.NotNil(t, tc)
+
+			require.NotNil(t, tc.Behavior)
+			assert.Equal(t, productcatalog.ExclusiveTaxBehavior, *tc.Behavior)
+
+			require.NotNil(t, tc.Stripe)
+			assert.Equal(t, "txcd_20000001", tc.Stripe.Code)
+
+			require.NotNil(t, tc.TaxCodeID)
+
+			tcEntity, err := findAddonTaxCodeByStripeCode(t, ctx, env.TaxCode, namespace, "txcd_20000001")
+			require.NoError(t, err)
+			assert.Equal(t, *tc.TaxCodeID, tcEntity.ID)
+
+			assertAddonRCDBCols(t, ctx, env, a.ID, features[0].Key, lo.ToPtr(tcEntity.ID), lo.ToPtr(productcatalog.ExclusiveTaxBehavior))
+		})
+
+		t.Run("BehaviorOnlyNoStripe", func(t *testing.T) {
+			input := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], &productcatalog.TaxConfig{
+				Behavior: lo.ToPtr(productcatalog.InclusiveTaxBehavior),
+			}))
+			input.Key = "addon-behavior-only"
+			input.Name = "Behavior Only"
+
+			a, err := env.Addon.CreateAddon(ctx, input)
+			require.NoError(t, err)
+
+			tc := getFirstAddonRCTaxConfig(t, a)
+			require.NotNil(t, tc)
+
+			require.NotNil(t, tc.Behavior)
+			assert.Equal(t, productcatalog.InclusiveTaxBehavior, *tc.Behavior)
+
+			assert.Nil(t, tc.Stripe, "Stripe should be nil when not provided")
+			assert.Nil(t, tc.TaxCodeID, "TaxCodeID should be nil when no Stripe code")
+
+			assertAddonRCDBCols(t, ctx, env, a.ID, features[0].Key, nil, lo.ToPtr(productcatalog.InclusiveTaxBehavior))
+		})
+
+		t.Run("ReuseExistingTaxCode", func(t *testing.T) {
+			// Create first addon with txcd_30000001
+			input1 := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], &productcatalog.TaxConfig{
+				Stripe: &productcatalog.StripeTaxConfig{Code: "txcd_30000001"},
+			}))
+			input1.Key = "addon-reuse-1"
+			input1.Name = "Reuse 1"
+
+			a1, err := env.Addon.CreateAddon(ctx, input1)
+			require.NoError(t, err)
+
+			tc1 := getFirstAddonRCTaxConfig(t, a1)
+			require.NotNil(t, tc1)
+			require.NotNil(t, tc1.TaxCodeID)
+
+			// Create second addon with same stripe code
+			input2 := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], &productcatalog.TaxConfig{
+				Stripe: &productcatalog.StripeTaxConfig{Code: "txcd_30000001"},
+			}))
+			input2.Key = "addon-reuse-2"
+			input2.Name = "Reuse 2"
+
+			a2, err := env.Addon.CreateAddon(ctx, input2)
+			require.NoError(t, err)
+
+			tc2 := getFirstAddonRCTaxConfig(t, a2)
+			require.NotNil(t, tc2)
+			require.NotNil(t, tc2.TaxCodeID)
+
+			// Both addons should reference the same TaxCode entity
+			assert.Equal(t, *tc1.TaxCodeID, *tc2.TaxCodeID, "both addons must reference the same TaxCode entity")
+
+			assertAddonRCDBCols(t, ctx, env, a1.ID, features[0].Key, lo.ToPtr(*tc1.TaxCodeID), nil)
+			assertAddonRCDBCols(t, ctx, env, a2.ID, features[0].Key, lo.ToPtr(*tc2.TaxCodeID), nil)
+		})
+
+		t.Run("MultipleDifferentStripeCodes", func(t *testing.T) {
+			rc1 := &productcatalog.FlatFeeRateCard{
+				RateCardMeta: productcatalog.RateCardMeta{
+					Key:  "rc-a",
+					Name: "RC A",
+					TaxConfig: &productcatalog.TaxConfig{
+						Stripe: &productcatalog.StripeTaxConfig{Code: "txcd_40000001"},
+					},
+					Price: productcatalog.NewPriceFrom(productcatalog.FlatPrice{
+						Amount:      decimal.NewFromInt(100),
+						PaymentTerm: productcatalog.InArrearsPaymentTerm,
+					}),
+				},
+				BillingCadence: &MonthPeriod,
+			}
+
+			rc2 := &productcatalog.FlatFeeRateCard{
+				RateCardMeta: productcatalog.RateCardMeta{
+					Key:  "rc-b",
+					Name: "RC B",
+					TaxConfig: &productcatalog.TaxConfig{
+						Stripe: &productcatalog.StripeTaxConfig{Code: "txcd_50000001"},
+					},
+					Price: productcatalog.NewPriceFrom(productcatalog.FlatPrice{
+						Amount:      decimal.NewFromInt(200),
+						PaymentTerm: productcatalog.InArrearsPaymentTerm,
+					}),
+				},
+				BillingCadence: &MonthPeriod,
+			}
+
+			input := pctestutils.NewTestAddon(t, namespace, rc1, rc2)
+			input.Key = "addon-multi-stripe"
+			input.Name = "Multi Stripe"
+
+			a, err := env.Addon.CreateAddon(ctx, input)
+			require.NoError(t, err)
+
+			require.Len(t, a.RateCards, 2)
+
+			rcMap := make(map[string]*productcatalog.TaxConfig)
+			for _, rc := range a.RateCards {
+				rcMap[rc.AsMeta().Key] = rc.AsMeta().TaxConfig
+			}
+
+			tcA := rcMap["rc-a"]
+			tcB := rcMap["rc-b"]
+
+			require.NotNil(t, tcA)
+			require.NotNil(t, tcA.TaxCodeID)
+			require.NotNil(t, tcB)
+			require.NotNil(t, tcB.TaxCodeID)
+
+			assert.NotEqual(t, *tcA.TaxCodeID, *tcB.TaxCodeID, "different stripe codes must create different TaxCode entities")
+
+			tcEntityA, err := findAddonTaxCodeByStripeCode(t, ctx, env.TaxCode, namespace, "txcd_40000001")
+			require.NoError(t, err)
+			tcEntityB, err := findAddonTaxCodeByStripeCode(t, ctx, env.TaxCode, namespace, "txcd_50000001")
+			require.NoError(t, err)
+			assertAddonRCDBCols(t, ctx, env, a.ID, "rc-a", lo.ToPtr(tcEntityA.ID), nil)
+			assertAddonRCDBCols(t, ctx, env, a.ID, "rc-b", lo.ToPtr(tcEntityB.ID), nil)
+		})
+
+		t.Run("TaxCodeIdOnly", func(t *testing.T) {
+			// Pre-create a TaxCode entity with a Stripe mapping.
+			tcEntity, err := env.TaxCode.GetOrCreateByAppMapping(ctx, taxcode.GetOrCreateByAppMappingInput{
+				Namespace: namespace,
+				AppType:   app.AppTypeStripe,
+				TaxCode:   "txcd_60000003",
+			})
+			require.NoError(t, err)
+
+			input := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], &productcatalog.TaxConfig{
+				TaxCodeID: lo.ToPtr(tcEntity.ID),
+			}))
+			input.Key = "addon-taxcodeid-only"
+			input.Name = "TaxCodeId Only"
+
+			a, err := env.Addon.CreateAddon(ctx, input)
+			require.NoError(t, err)
+
+			tc := getFirstAddonRCTaxConfig(t, a)
+			require.NotNil(t, tc)
+			require.NotNil(t, tc.TaxCodeID)
+			assert.Equal(t, tcEntity.ID, *tc.TaxCodeID)
+
+			// Stripe code should be backfilled from the TaxCode entity's app mapping.
+			require.NotNil(t, tc.Stripe, "Stripe must be backfilled from TaxCode app mapping")
+			assert.Equal(t, "txcd_60000003", tc.Stripe.Code)
+
+			assertAddonRCDBCols(t, ctx, env, a.ID, features[0].Key, lo.ToPtr(tcEntity.ID), nil)
+		})
+
+		t.Run("TaxCodeIdNotFound", func(t *testing.T) {
+			input := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], &productcatalog.TaxConfig{
+				TaxCodeID: lo.ToPtr("01JNON_EXISTENT_TAX_CODE_ID"),
+			}))
+			input.Key = "addon-taxcodeid-not-found"
+			input.Name = "TaxCodeId Not Found"
+
+			_, err := env.Addon.CreateAddon(ctx, input)
+			require.Error(t, err)
+			assert.True(t, models.IsGenericValidationError(err), "expected validation error for unknown taxCodeId, got: %v", err)
+		})
+	})
+
+	t.Run("Update", func(t *testing.T) {
+		t.Run("AddTaxConfig", func(t *testing.T) {
+			// Create addon without TaxConfig
+			input := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], nil))
+			input.Key = "addon-update-add-tax"
+			input.Name = "Update Add Tax"
+
+			a, err := env.Addon.CreateAddon(ctx, input)
+			require.NoError(t, err)
+
+			tc := getFirstAddonRCTaxConfig(t, a)
+			assert.Nil(t, tc)
+
+			// Update to add TaxConfig with Stripe code
+			updatedRateCards := productcatalog.RateCards{
+				newTestAddonFlatRateCard(features[0], &productcatalog.TaxConfig{
+					Stripe: &productcatalog.StripeTaxConfig{Code: "txcd_70000001"},
+				}),
+			}
+
+			updated, err := env.Addon.UpdateAddon(ctx, addon.UpdateAddonInput{
+				NamespacedID: a.NamespacedID,
+				RateCards:    &updatedRateCards,
+			})
+			require.NoError(t, err)
+
+			tc = getFirstAddonRCTaxConfig(t, updated)
+			require.NotNil(t, tc)
+			require.NotNil(t, tc.Stripe)
+			assert.Equal(t, "txcd_70000001", tc.Stripe.Code)
+			require.NotNil(t, tc.TaxCodeID, "TaxCodeID must be populated after update")
+
+			tcEntity, err := findAddonTaxCodeByStripeCode(t, ctx, env.TaxCode, namespace, "txcd_70000001")
+			require.NoError(t, err)
+			assert.Equal(t, *tc.TaxCodeID, tcEntity.ID)
+
+			assertAddonRCDBCols(t, ctx, env, updated.ID, features[0].Key, lo.ToPtr(tcEntity.ID), nil)
+		})
+
+		t.Run("ChangeStripeCode", func(t *testing.T) {
+			input := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], &productcatalog.TaxConfig{
+				Stripe: &productcatalog.StripeTaxConfig{Code: "txcd_80000001"},
+			}))
+			input.Key = "addon-update-change-code"
+			input.Name = "Update Change Code"
+
+			a, err := env.Addon.CreateAddon(ctx, input)
+			require.NoError(t, err)
+
+			oldTC := getFirstAddonRCTaxConfig(t, a)
+			require.NotNil(t, oldTC)
+			require.NotNil(t, oldTC.TaxCodeID)
+			oldTaxCodeID := *oldTC.TaxCodeID
+
+			// Update to different stripe code
+			updatedRateCards := productcatalog.RateCards{
+				newTestAddonFlatRateCard(features[0], &productcatalog.TaxConfig{
+					Stripe: &productcatalog.StripeTaxConfig{Code: "txcd_90000001"},
+				}),
+			}
+
+			updated, err := env.Addon.UpdateAddon(ctx, addon.UpdateAddonInput{
+				NamespacedID: a.NamespacedID,
+				RateCards:    &updatedRateCards,
+			})
+			require.NoError(t, err)
+
+			newTC := getFirstAddonRCTaxConfig(t, updated)
+			require.NotNil(t, newTC)
+			require.NotNil(t, newTC.Stripe)
+			assert.Equal(t, "txcd_90000001", newTC.Stripe.Code)
+			require.NotNil(t, newTC.TaxCodeID)
+
+			assert.NotEqual(t, oldTaxCodeID, *newTC.TaxCodeID, "new stripe code must create a new TaxCode entity")
+
+			// Old TaxCode entity should still exist
+			_, err = findAddonTaxCodeByStripeCode(t, ctx, env.TaxCode, namespace, "txcd_80000001")
+			assert.NoError(t, err, "old TaxCode entity should still exist")
+
+			newTCEntity, err := findAddonTaxCodeByStripeCode(t, ctx, env.TaxCode, namespace, "txcd_90000001")
+			require.NoError(t, err)
+			assertAddonRCDBCols(t, ctx, env, updated.ID, features[0].Key, lo.ToPtr(newTCEntity.ID), nil)
+		})
+
+		t.Run("UpdateWithTaxCodeId", func(t *testing.T) {
+			input := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], nil))
+			input.Key = "addon-update-taxcodeid"
+			input.Name = "Update TaxCodeId"
+
+			a, err := env.Addon.CreateAddon(ctx, input)
+			require.NoError(t, err)
+
+			tcEntity, err := env.TaxCode.GetOrCreateByAppMapping(ctx, taxcode.GetOrCreateByAppMappingInput{
+				Namespace: namespace,
+				AppType:   app.AppTypeStripe,
+				TaxCode:   "txcd_60000004",
+			})
+			require.NoError(t, err)
+
+			updatedRateCards := productcatalog.RateCards{
+				newTestAddonFlatRateCard(features[0], &productcatalog.TaxConfig{
+					TaxCodeID: lo.ToPtr(tcEntity.ID),
+				}),
+			}
+
+			updated, err := env.Addon.UpdateAddon(ctx, addon.UpdateAddonInput{
+				NamespacedID: a.NamespacedID,
+				RateCards:    &updatedRateCards,
+			})
+			require.NoError(t, err)
+
+			tc := getFirstAddonRCTaxConfig(t, updated)
+			require.NotNil(t, tc)
+			require.NotNil(t, tc.TaxCodeID)
+			assert.Equal(t, tcEntity.ID, *tc.TaxCodeID)
+			require.NotNil(t, tc.Stripe, "Stripe must be backfilled from TaxCode app mapping")
+			assert.Equal(t, "txcd_60000004", tc.Stripe.Code)
+
+			assertAddonRCDBCols(t, ctx, env, updated.ID, features[0].Key, lo.ToPtr(tcEntity.ID), nil)
+		})
+
+		t.Run("RemoveTaxConfig", func(t *testing.T) {
+			input := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], &productcatalog.TaxConfig{
+				Stripe: &productcatalog.StripeTaxConfig{Code: "txcd_11000001"},
+			}))
+			input.Key = "addon-update-remove-tax"
+			input.Name = "Update Remove Tax"
+
+			a, err := env.Addon.CreateAddon(ctx, input)
+			require.NoError(t, err)
+
+			tc := getFirstAddonRCTaxConfig(t, a)
+			require.NotNil(t, tc)
+			require.NotNil(t, tc.TaxCodeID)
+
+			// Update to remove TaxConfig
+			updatedRateCards := productcatalog.RateCards{
+				newTestAddonFlatRateCard(features[0], nil),
+			}
+
+			updated, err := env.Addon.UpdateAddon(ctx, addon.UpdateAddonInput{
+				NamespacedID: a.NamespacedID,
+				RateCards:    &updatedRateCards,
+			})
+			require.NoError(t, err)
+
+			tc = getFirstAddonRCTaxConfig(t, updated)
+			assert.Nil(t, tc, "TaxConfig should be nil after removal")
+
+			// TaxCode entity should still exist (orphaned, not deleted)
+			_, err = findAddonTaxCodeByStripeCode(t, ctx, env.TaxCode, namespace, "txcd_11000001")
+			assert.NoError(t, err, "TaxCode entity should not be deleted")
+
+			assertAddonRCDBCols(t, ctx, env, updated.ID, features[0].Key, nil, nil)
+		})
+
+		t.Run("MetadataOnlyUpdate", func(t *testing.T) {
+			input := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], &productcatalog.TaxConfig{
+				Stripe: &productcatalog.StripeTaxConfig{Code: "txcd_12000001"},
+			}))
+			input.Key = "addon-update-metadata-only"
+			input.Name = "Update Metadata Only"
+
+			a, err := env.Addon.CreateAddon(ctx, input)
+			require.NoError(t, err)
+
+			tc := getFirstAddonRCTaxConfig(t, a)
+			require.NotNil(t, tc)
+			require.NotNil(t, tc.TaxCodeID)
+			originalTaxCodeID := *tc.TaxCodeID
+
+			// Update only addon name, no ratecards
+			updated, err := env.Addon.UpdateAddon(ctx, addon.UpdateAddonInput{
+				NamespacedID: a.NamespacedID,
+				Name:         lo.ToPtr("Updated Name"),
+			})
+			require.NoError(t, err)
+
+			tc = getFirstAddonRCTaxConfig(t, updated)
+			require.NotNil(t, tc)
+			require.NotNil(t, tc.TaxCodeID)
+			assert.Equal(t, originalTaxCodeID, *tc.TaxCodeID, "TaxCodeID should be unchanged on metadata-only update")
+
+			assertAddonRCDBCols(t, ctx, env, updated.ID, features[0].Key, lo.ToPtr(originalTaxCodeID), nil)
+		})
+	})
+
+	t.Run("ReadBackVerification", func(t *testing.T) {
+		t.Run("BackfillFromNewColumns", func(t *testing.T) {
+			// Create addon with full TaxConfig (Stripe + Behavior)
+			input := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], &productcatalog.TaxConfig{
+				Behavior: lo.ToPtr(productcatalog.ExclusiveTaxBehavior),
+				Stripe:   &productcatalog.StripeTaxConfig{Code: "txcd_13000001"},
+			}))
+			input.Key = "addon-readback-verify"
+			input.Name = "Readback Verify"
+
+			a, err := env.Addon.CreateAddon(ctx, input)
+			require.NoError(t, err)
+
+			// Re-read the addon
+			fetched, err := env.Addon.GetAddon(ctx, addon.GetAddonInput{
+				NamespacedID: a.NamespacedID,
+			})
+			require.NoError(t, err)
+
+			tc := getFirstAddonRCTaxConfig(t, fetched)
+			require.NotNil(t, tc)
+
+			// Behavior should be present
+			require.NotNil(t, tc.Behavior)
+			assert.Equal(t, productcatalog.ExclusiveTaxBehavior, *tc.Behavior)
+
+			// Stripe should be present
+			require.NotNil(t, tc.Stripe)
+			assert.Equal(t, "txcd_13000001", tc.Stripe.Code)
+
+			tcEntity13, err := findAddonTaxCodeByStripeCode(t, ctx, env.TaxCode, namespace, "txcd_13000001")
+			require.NoError(t, err)
+			assertAddonRCDBCols(t, ctx, env, fetched.ID, features[0].Key, lo.ToPtr(tcEntity13.ID), lo.ToPtr(productcatalog.ExclusiveTaxBehavior))
+		})
+	})
+}
+
+func TestAddonTaxCodeBackfill(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	env := pctestutils.NewTestEnv(t)
+	t.Cleanup(func() { env.Close(t) })
+	taxCodeEnv := taxcodetestutils.NewTestEnvFromClient(t, env.Client, nil)
+
+	namespace := pctestutils.NewTestNamespace(t)
+
+	// Setup meters and features
+	err := env.Meter.ReplaceMeters(ctx, pctestutils.NewTestMeters(t, namespace))
+	require.NoError(t, err)
+
+	result, err := env.Meter.ListMeters(ctx, meter.ListMetersParams{
+		Page:      pagination.Page{PageSize: 1000, PageNumber: 1},
+		Namespace: namespace,
+	})
+	require.NoError(t, err)
+	require.NotEmpty(t, result.Items)
+
+	features := make([]feature.Feature, 0, len(result.Items))
+	for _, m := range result.Items {
+		feat, err := env.Feature.CreateFeature(ctx, pctestutils.NewTestFeatureFromMeter(t, &m))
+		require.NoError(t, err)
+		features = append(features, feat)
+	}
+
+	t.Run("BackfillFromDedicatedColumns", func(t *testing.T) {
+		// Create an addon via service to get an addon ID
+		input := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], nil))
+		input.Key = "backfill-addon-test"
+		input.Name = "Backfill Addon Test"
+
+		a, err := env.Addon.CreateAddon(ctx, input)
+		require.NoError(t, err)
+
+		tcEntity := taxCodeEnv.CreateTaxCode(t, namespace, taxcode.CreateTaxCodeInput{
+			Key:  "stripe_txcd_99000002",
+			Name: "txcd_99000002",
+			AppMappings: taxcode.TaxCodeAppMappings{
+				{AppType: app.AppTypeStripe, TaxCode: "txcd_99000002"},
+			},
+		})
+
+		// Insert an AddonRateCard row directly — no tax_config JSONB, only dedicated columns
+		behavior := productcatalog.ExclusiveTaxBehavior
+		_, err = env.Client.AddonRateCard.Create().
+			SetAddonID(a.ID).
+			SetNamespace(namespace).
+			SetKey("backfill-rc").
+			SetType(productcatalog.FlatFeeRateCardType).
+			SetName("Backfill RC").
+			SetMetadata(map[string]string{}).
+			SetEntitlementTemplate(nil).
+			SetDiscounts(nil).
+			SetTaxCodeID(tcEntity.ID).
+			SetTaxBehavior(behavior).
+			Save(ctx)
+		require.NoError(t, err)
+
+		// Read via service — adapter must backfill TaxConfig from dedicated columns
+		fetched, err := env.Addon.GetAddon(ctx, addon.GetAddonInput{
+			NamespacedID: a.NamespacedID,
+		})
+		require.NoError(t, err)
+
+		var backfillRC *addon.RateCard
+		for i, rc := range fetched.RateCards {
+			if rc.AsMeta().Key == "backfill-rc" {
+				backfillRC = &fetched.RateCards[i]
+				break
+			}
+		}
+		require.NotNil(t, backfillRC, "backfill rate card must be present in addon")
+
+		tc := backfillRC.AsMeta().TaxConfig
+		require.NotNil(t, tc, "TaxConfig must be backfilled from dedicated columns")
+		require.NotNil(t, tc.Stripe, "Stripe code must be backfilled from TaxCode entity")
+		assert.Equal(t, "txcd_99000002", tc.Stripe.Code)
+		require.NotNil(t, tc.Behavior, "Behavior must be backfilled from tax_behavior column")
+		assert.Equal(t, productcatalog.ExclusiveTaxBehavior, *tc.Behavior)
+		require.NotNil(t, tc.TaxCodeID, "TaxCodeID must be backfilled from TaxCode entity")
+		assert.Equal(t, tcEntity.ID, *tc.TaxCodeID)
+	})
+
+	t.Run("BackfillTaxCodeOnly", func(t *testing.T) {
+		input := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], nil))
+		input.Key = "backfill-taxcode-only"
+		input.Name = "Backfill TaxCode Only"
+
+		a, err := env.Addon.CreateAddon(ctx, input)
+		require.NoError(t, err)
+
+		tcEntity := taxCodeEnv.CreateTaxCode(t, namespace, taxcode.CreateTaxCodeInput{
+			Key:  "stripe_txcd_99000010",
+			Name: "txcd_99000010",
+			AppMappings: taxcode.TaxCodeAppMappings{
+				{AppType: app.AppTypeStripe, TaxCode: "txcd_99000010"},
+			},
+		})
+
+		// Only tax_code_id, no tax_behavior
+		_, err = env.Client.AddonRateCard.Create().
+			SetAddonID(a.ID).
+			SetNamespace(namespace).
+			SetKey("backfill-tc-only").
+			SetType(productcatalog.FlatFeeRateCardType).
+			SetName("Backfill TC Only").
+			SetMetadata(map[string]string{}).
+			SetEntitlementTemplate(nil).
+			SetDiscounts(nil).
+			SetTaxCodeID(tcEntity.ID).
+			Save(ctx)
+		require.NoError(t, err)
+
+		fetched, err := env.Addon.GetAddon(ctx, addon.GetAddonInput{NamespacedID: a.NamespacedID})
+		require.NoError(t, err)
+
+		var backfillRC *addon.RateCard
+		for i, rc := range fetched.RateCards {
+			if rc.AsMeta().Key == "backfill-tc-only" {
+				backfillRC = &fetched.RateCards[i]
+				break
+			}
+		}
+		require.NotNil(t, backfillRC)
+
+		tc := backfillRC.AsMeta().TaxConfig
+		require.NotNil(t, tc, "TaxConfig must be backfilled from TaxCode entity alone")
+		require.NotNil(t, tc.Stripe)
+		assert.Equal(t, "txcd_99000010", tc.Stripe.Code)
+		assert.Nil(t, tc.Behavior, "Behavior must be nil when tax_behavior column is not set")
+		require.NotNil(t, tc.TaxCodeID, "TaxCodeID must be backfilled from TaxCode entity")
+		assert.Equal(t, tcEntity.ID, *tc.TaxCodeID)
+	})
+
+	t.Run("BackfillBehaviorOnly", func(t *testing.T) {
+		input := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], nil))
+		input.Key = "backfill-behavior-only"
+		input.Name = "Backfill Behavior Only"
+
+		a, err := env.Addon.CreateAddon(ctx, input)
+		require.NoError(t, err)
+
+		// Only tax_behavior, no tax_code_id
+		behavior := productcatalog.InclusiveTaxBehavior
+		_, err = env.Client.AddonRateCard.Create().
+			SetAddonID(a.ID).
+			SetNamespace(namespace).
+			SetKey("backfill-beh-only").
+			SetType(productcatalog.FlatFeeRateCardType).
+			SetName("Backfill Behavior Only").
+			SetMetadata(map[string]string{}).
+			SetEntitlementTemplate(nil).
+			SetDiscounts(nil).
+			SetTaxBehavior(behavior).
+			Save(ctx)
+		require.NoError(t, err)
+
+		fetched, err := env.Addon.GetAddon(ctx, addon.GetAddonInput{NamespacedID: a.NamespacedID})
+		require.NoError(t, err)
+
+		var backfillRC *addon.RateCard
+		for i, rc := range fetched.RateCards {
+			if rc.AsMeta().Key == "backfill-beh-only" {
+				backfillRC = &fetched.RateCards[i]
+				break
+			}
+		}
+		require.NotNil(t, backfillRC)
+
+		tc := backfillRC.AsMeta().TaxConfig
+		require.NotNil(t, tc, "TaxConfig must be backfilled from tax_behavior column alone")
+		require.NotNil(t, tc.Behavior)
+		assert.Equal(t, productcatalog.InclusiveTaxBehavior, *tc.Behavior)
+		assert.Nil(t, tc.Stripe, "Stripe must be nil when no TaxCode entity is linked")
+	})
+}
+
+func TestAddonWithPlanTaxCode(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	env := pctestutils.NewTestEnv(t)
+	t.Cleanup(func() { env.Close(t) })
+	taxCodeEnv := taxcodetestutils.NewTestEnvFromClient(t, env.Client, nil)
+
+	namespace := pctestutils.NewTestNamespace(t)
+
+	err := env.Meter.ReplaceMeters(ctx, pctestutils.NewTestMeters(t, namespace))
+	require.NoError(t, err)
+
+	result, err := env.Meter.ListMeters(ctx, meter.ListMetersParams{
+		Page:      pagination.Page{PageSize: 1000, PageNumber: 1},
+		Namespace: namespace,
+	})
+	require.NoError(t, err)
+	require.NotEmpty(t, result.Items)
+
+	features := make([]feature.Feature, 0, len(result.Items))
+	for _, m := range result.Items {
+		feat, err := env.Feature.CreateFeature(ctx, pctestutils.NewTestFeatureFromMeter(t, &m))
+		require.NoError(t, err)
+		features = append(features, feat)
+	}
+
+	t.Run("BackfillPlanRateCardInAddonResponse", func(t *testing.T) {
+		// Create and publish an addon so it can be attached to a plan.
+		addonInput := newTestAddonInput(t, namespace, newTestAddonFlatRateCard(features[0], nil))
+		addonInput.Key = "addon-with-plan-backfill"
+		addonInput.Name = "Addon With Plan Backfill"
+
+		a, err := env.Addon.CreateAddon(ctx, addonInput)
+		require.NoError(t, err)
+
+		publishAt := time.Now().Truncate(time.Microsecond)
+		a, err = env.Addon.PublishAddon(ctx, addon.PublishAddonInput{
+			NamespacedID:    a.NamespacedID,
+			EffectivePeriod: productcatalog.EffectivePeriod{EffectiveFrom: &publishAt},
+		})
+		require.NoError(t, err)
+
+		// Create a plan. Rate card billing cadence must match the plan's P1M cadence.
+		planInput := pctestutils.NewTestPlan(t, namespace,
+			pctestutils.WithPlanPhases(productcatalog.Phase{
+				PhaseMeta: productcatalog.PhaseMeta{Key: "default", Name: "Default"},
+				RateCards: productcatalog.RateCards{
+					&productcatalog.FlatFeeRateCard{
+						RateCardMeta: productcatalog.RateCardMeta{
+							Key:        features[0].Key,
+							Name:       features[0].Name,
+							FeatureKey: lo.ToPtr(features[0].Key),
+							FeatureID:  lo.ToPtr(features[0].ID),
+							Price: productcatalog.NewPriceFrom(productcatalog.FlatPrice{
+								Amount:      decimal.NewFromInt(100),
+								PaymentTerm: productcatalog.InArrearsPaymentTerm,
+							}),
+						},
+						BillingCadence: &pctestutils.MonthPeriod,
+					},
+				},
+			}),
+			func(t *testing.T, p *productcatalog.Plan) {
+				t.Helper()
+
+				p.Key = "plan-for-addon-backfill"
+				p.Name = "Plan For Addon Backfill"
+			},
+		)
+
+		p, err := env.Plan.CreatePlan(ctx, planInput)
+		require.NoError(t, err)
+		require.NotEmpty(t, p.Phases)
+
+		// Attach the plan to the addon.
+		_, err = env.PlanAddon.CreatePlanAddon(ctx, planaddon.CreatePlanAddonInput{
+			NamespacedModel: models.NamespacedModel{Namespace: namespace},
+			PlanID:          p.ID,
+			AddonID:         a.ID,
+			FromPlanPhase:   p.Phases[0].Key,
+		})
+		require.NoError(t, err)
+
+		phaseID := p.Phases[0].PhaseManagedFields.NamespacedID.ID
+
+		tcEntity := taxCodeEnv.CreateTaxCode(t, namespace, taxcode.CreateTaxCodeInput{
+			Key:  "stripe_txcd_99000020",
+			Name: "txcd_99000020",
+			AppMappings: taxcode.TaxCodeAppMappings{
+				{AppType: app.AppTypeStripe, TaxCode: "txcd_99000020"},
+			},
+		})
+
+		// Insert a PlanRateCard row directly with only dedicated tax columns — no tax_config JSONB.
+		// This simulates the legacy schema where TaxConfig is stored in separate columns rather than JSONB.
+		behavior := productcatalog.ExclusiveTaxBehavior
+		_, err = env.Client.PlanRateCard.Create().
+			SetPhaseID(phaseID).
+			SetNamespace(namespace).
+			SetKey("backfill-plan-rc").
+			SetType(productcatalog.FlatFeeRateCardType).
+			SetName("Backfill Plan RC").
+			SetMetadata(map[string]string{}).
+			SetEntitlementTemplate(nil).
+			SetDiscounts(nil).
+			SetTaxCodeID(tcEntity.ID).
+			SetTaxBehavior(behavior).
+			Save(ctx)
+		require.NoError(t, err)
+
+		// Fetch the addon with plans expanded. Plan rate cards are mapped through
+		// addon/adapter.FromPlanRateCardRow — the path fixed by the backfill change.
+		fetched, err := env.Addon.GetAddon(ctx, addon.GetAddonInput{
+			NamespacedID: a.NamespacedID,
+			Expand:       addon.ExpandFields{PlanAddons: true},
+		})
+		require.NoError(t, err)
+		require.NotNil(t, fetched.Plans, "Plans must be expanded in addon response")
+		require.Len(t, *fetched.Plans, 1)
+
+		planInAddon := (*fetched.Plans)[0]
+		require.NotEmpty(t, planInAddon.Phases, "plan phases must be present in addon response")
+
+		var backfillRC productcatalog.RateCard
+		for _, rc := range planInAddon.Phases[0].RateCards {
+			if rc.AsMeta().Key == "backfill-plan-rc" {
+				backfillRC = rc
+				break
+			}
+		}
+		require.NotNil(t, backfillRC, "backfill plan rate card must be present in addon response")
+
+		tc := backfillRC.AsMeta().TaxConfig
+		require.NotNil(t, tc, "TaxConfig must be backfilled from dedicated columns via addon adapter path")
+		require.NotNil(t, tc.Stripe, "Stripe code must be backfilled from TaxCode entity")
+		assert.Equal(t, "txcd_99000020", tc.Stripe.Code)
+		require.NotNil(t, tc.Behavior, "Behavior must be backfilled from tax_behavior column")
+		assert.Equal(t, productcatalog.ExclusiveTaxBehavior, *tc.Behavior)
+		require.NotNil(t, tc.TaxCodeID, "TaxCodeID must be backfilled from TaxCode entity")
+		assert.Equal(t, tcEntity.ID, *tc.TaxCodeID)
+	})
+}

openmeter/productcatalog/addon/validators.go

@@ -0,0 +1,31 @@
+package addon
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/samber/lo"
+
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+func IsAddonDeleted(at time.Time) models.ValidatorFunc[Addon] {
+	return func(a Addon) error {
+		if a.IsDeleted() {
+			return fmt.Errorf("add-on is deleted [deleted_at=%s]", *a.DeletedAt)
+		}
+
+		return nil
+	}
+}
+
+func HasAddonStatus(statuses ...productcatalog.AddonStatus) models.ValidatorFunc[Addon] {
+	return func(a Addon) error {
+		if !lo.Contains(statuses, a.Status()) {
+			return fmt.Errorf("invalid %s status, allowed statuses: %+v", a.Status(), statuses)
+		}
+
+		return nil
+	}
+}

openmeter/productcatalog/alignment.go

@@ -0,0 +1,35 @@
+package productcatalog
+
+import (
+	"github.com/openmeterio/openmeter/pkg/datetime"
+)
+
+// Alignment means that either
+// - the two cadences are identical
+// - if a RateCard's cadence is "longer" than the Plan's cadence, the plan cadence must "divide" without remainder the ratecard's cadence
+// - if a RateCard's cadence is "shorter" than the Plan's cadence, the ratecard's cadence must "divide" without remainder the plan's cadence
+// "longer" and "shorter" are not generally meaningful terms for periods, as for instance sometimes P1M equals P4W, sometimes its longer.
+func ValidateBillingCadencesAlign(planBillingCadence datetime.ISODuration, rateCardBillingCadence datetime.ISODuration) error {
+	pSimple := planBillingCadence.Simplify(true)
+	rcSimple := rateCardBillingCadence.Simplify(true)
+
+	// If the two cadences are identical, we're good
+	if pSimple.Equal(&rcSimple) {
+		return nil
+	}
+
+	// We'll leverage the fact that Period.DibisibleBy() works correctly regardless which period is larger,
+	// so we'll just test both ways
+
+	ok, err := pSimple.DivisibleBy(rcSimple)
+	if ok && err == nil {
+		return nil
+	}
+
+	ok, err = rcSimple.DivisibleBy(pSimple)
+	if ok && err == nil {
+		return nil
+	}
+
+	return ErrRateCardBillingCadenceUnaligned
+}

openmeter/productcatalog/discount.go

@@ -0,0 +1,239 @@
+package productcatalog
+
+import (
+	"errors"
+
+	decimal "github.com/alpacahq/alpacadecimal"
+	"github.com/samber/lo"
+
+	"github.com/openmeterio/openmeter/pkg/equal"
+	"github.com/openmeterio/openmeter/pkg/hasher"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+var (
+	_ models.Validator                           = (*PercentageDiscount)(nil)
+	_ hasher.Hasher                              = (*PercentageDiscount)(nil)
+	_ models.Clonable[PercentageDiscount]        = (*PercentageDiscount)(nil)
+	_ models.CustomValidator[PercentageDiscount] = (*PercentageDiscount)(nil)
+)
+
+type PercentageDiscount struct {
+	// Percentage defines percentage of the discount.
+	Percentage models.Percentage `json:"percentage"`
+}
+
+func (d PercentageDiscount) Hash() hasher.Hash {
+	var content string
+
+	content += d.Percentage.String()
+
+	return hasher.NewHash([]byte(content))
+}
+
+func (d PercentageDiscount) ValidateWith(v ...models.ValidatorFunc[PercentageDiscount]) error {
+	return models.Validate(d, v...)
+}
+
+func PercentageDiscountWithValidValue() models.ValidatorFunc[PercentageDiscount] {
+	return func(d PercentageDiscount) error {
+		if d.Percentage.LessThan(decimal.Zero) || d.Percentage.GreaterThan(decimal.NewFromInt(100)) {
+			return ErrPercentageDiscountInvalidValue
+		}
+
+		return nil
+	}
+}
+
+func (d PercentageDiscount) Validate() error {
+	return d.ValidateWith(PercentageDiscountWithValidValue())
+}
+
+func (d PercentageDiscount) ValidateForPrice(_ *Price) error {
+	return d.Validate()
+}
+
+func (d PercentageDiscount) Clone() PercentageDiscount {
+	return PercentageDiscount{
+		Percentage: d.Percentage,
+	}
+}
+
+var (
+	_ models.Validator                      = (*UsageDiscount)(nil)
+	_ hasher.Hasher                         = (*UsageDiscount)(nil)
+	_ models.Clonable[UsageDiscount]        = (*UsageDiscount)(nil)
+	_ models.CustomValidator[UsageDiscount] = (*UsageDiscount)(nil)
+)
+
+type UsageDiscount struct {
+	Quantity decimal.Decimal `json:"quantity"`
+}
+
+func (d UsageDiscount) Hash() hasher.Hash {
+	var content string
+
+	content += d.Quantity.String()
+
+	return hasher.NewHash([]byte(content))
+}
+
+func (d UsageDiscount) ValidateWith(v ...models.ValidatorFunc[UsageDiscount]) error {
+	return models.Validate(d, v...)
+}
+
+func UsageDiscountWithValidValue() models.ValidatorFunc[UsageDiscount] {
+	return func(d UsageDiscount) error {
+		if d.Quantity.LessThan(decimal.Zero) {
+			return ErrUsageDiscountNegativeQuantity
+		}
+
+		return nil
+	}
+}
+
+func UsageDiscountWithPrice(price *Price) models.ValidatorFunc[UsageDiscount] {
+	return func(d UsageDiscount) error {
+		var errs []error
+
+		if price == nil {
+			// We cannot validate usage discount without a price.
+			return errors.New("price is required for usage discount")
+		}
+
+		if err := d.Validate(); err != nil {
+			errs = append(errs, err)
+		}
+
+		if price.Type() == FlatPriceType {
+			errs = append(errs, ErrUsageDiscountWithFlatPrice)
+		}
+
+		return errors.Join(errs...)
+	}
+}
+
+func (d UsageDiscount) Validate() error {
+	return d.ValidateWith(UsageDiscountWithValidValue())
+}
+
+func (d UsageDiscount) ValidateForPrice(price *Price) error {
+	return d.ValidateWith(UsageDiscountWithPrice(price))
+}
+
+func (d UsageDiscount) Clone() UsageDiscount {
+	return UsageDiscount{
+		Quantity: d.Quantity,
+	}
+}
+
+var (
+	_ models.Equaler[Discounts]  = (*Discounts)(nil)
+	_ models.Clonable[Discounts] = (*Discounts)(nil)
+	_ models.Validator           = (*Discounts)(nil)
+)
+
+type Discounts struct {
+	Percentage *PercentageDiscount `json:"percentage,omitempty"`
+	Usage      *UsageDiscount      `json:"usage,omitempty"`
+}
+
+func (d Discounts) Equal(v Discounts) bool {
+	if !equal.HasherPtrEqual(d.Percentage, v.Percentage) {
+		return false
+	}
+
+	if !equal.HasherPtrEqual(d.Usage, v.Usage) {
+		return false
+	}
+
+	return true
+}
+
+func (d Discounts) Clone() Discounts {
+	out := Discounts{}
+
+	if d.Percentage != nil {
+		out.Percentage = lo.ToPtr(d.Percentage.Clone())
+	}
+
+	if d.Usage != nil {
+		out.Usage = lo.ToPtr(d.Usage.Clone())
+	}
+
+	return out
+}
+
+func (d *Discounts) Validate() error {
+	var errs []error
+
+	if d == nil {
+		return nil
+	}
+
+	if d.Percentage != nil {
+		if err := d.Percentage.Validate(); err != nil {
+			errs = append(errs, models.ErrorWithFieldPrefix(
+				models.NewFieldSelectorGroup(models.NewFieldSelector("percentage")),
+				err),
+			)
+		}
+	}
+
+	if d.Usage != nil {
+		if err := d.Usage.Validate(); err != nil {
+			errs = append(errs, models.ErrorWithFieldPrefix(
+				models.NewFieldSelectorGroup(models.NewFieldSelector("usage")),
+				err),
+			)
+		}
+	}
+
+	if err := errors.Join(errs...); err != nil {
+		return models.NewGenericValidationError(models.ErrorWithFieldPrefix(
+			models.NewFieldSelectorGroup(models.NewFieldSelector("discounts")),
+			err),
+		)
+	}
+
+	return nil
+}
+
+func (d Discounts) ValidateForPrice(price *Price) error {
+	var errs []error
+
+	if !d.IsEmpty() && price == nil {
+		return errors.New("price is required for discounts")
+	}
+
+	if d.Percentage != nil {
+		if err := d.Percentage.ValidateForPrice(price); err != nil {
+			errs = append(errs, models.ErrorWithFieldPrefix(
+				models.NewFieldSelectorGroup(models.NewFieldSelector("percentage")),
+				err),
+			)
+		}
+	}
+
+	if d.Usage != nil {
+		if err := d.Usage.ValidateForPrice(price); err != nil {
+			errs = append(errs, models.ErrorWithFieldPrefix(
+				models.NewFieldSelectorGroup(models.NewFieldSelector("usage")),
+				err),
+			)
+		}
+	}
+
+	if err := errors.Join(errs...); err != nil {
+		return models.NewGenericValidationError(models.ErrorWithFieldPrefix(
+			models.NewFieldSelectorGroup(models.NewFieldSelector("discounts")),
+			err),
+		)
+	}
+
+	return nil
+}
+
+func (d Discounts) IsEmpty() bool {
+	return lo.IsEmpty(d)
+}

openmeter/productcatalog/discount_test.go

@@ -0,0 +1,161 @@
+package productcatalog
+
+import (
+	"testing"
+
+	decimal "github.com/alpacahq/alpacadecimal"
+	json "github.com/json-iterator/go"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+func TestDiscount_JSON(t *testing.T) {
+	tests := []struct {
+		Name          string
+		Discounts     Discounts
+		ExpectedError bool
+	}{
+		{
+			Name: "Valid - percentage",
+			Discounts: Discounts{
+				Percentage: &PercentageDiscount{
+					Percentage: models.NewPercentage(99.9),
+				},
+			},
+		},
+		{
+			Name: "Valid - usage",
+			Discounts: Discounts{
+				Usage: &UsageDiscount{
+					Quantity: decimal.NewFromInt(100),
+				},
+			},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.Name, func(t *testing.T) {
+			b, err := json.Marshal(&test.Discounts)
+			require.NoError(t, err)
+
+			t.Logf("Serialized Discount: %s", string(b))
+
+			d := Discounts{}
+			err = json.Unmarshal(b, &d)
+			require.NoError(t, err)
+
+			assert.Equal(t, test.Discounts, d)
+		})
+	}
+}
+
+func TestDiscountsEqual(t *testing.T) {
+	tests := []struct {
+		Name string
+
+		Left  Discounts
+		Right Discounts
+
+		ExpectedResult bool
+	}{
+		{
+			Name: "Equal",
+			Left: Discounts{
+				Percentage: &PercentageDiscount{
+					Percentage: models.NewPercentage(100),
+				},
+			},
+			Right: Discounts{
+				Percentage: &PercentageDiscount{
+					Percentage: models.NewPercentage(100),
+				},
+			},
+			ExpectedResult: true,
+		},
+		{
+			Name: "Diff",
+			Left: Discounts{
+				Percentage: &PercentageDiscount{
+					Percentage: models.NewPercentage(100),
+				},
+			},
+			Right: Discounts{
+				Usage: &UsageDiscount{
+					Quantity: decimal.NewFromInt(100),
+				},
+			},
+			ExpectedResult: false,
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.Name, func(t *testing.T) {
+			match := test.Left.Equal(test.Right)
+			assert.Equal(t, test.ExpectedResult, match)
+		})
+	}
+}
+
+func TestDiscountsValidateForPrice(t *testing.T) {
+	tests := []struct {
+		Name string
+
+		Discounts Discounts
+
+		ExpectedError bool
+	}{
+		{
+			Name: "Valid",
+			Discounts: Discounts{
+				Percentage: &PercentageDiscount{
+					Percentage: models.NewPercentage(50),
+				},
+			},
+			ExpectedError: false,
+		},
+		{
+			Name: "Invalid - more than 100% percentage discount",
+			Discounts: Discounts{
+				Percentage: &PercentageDiscount{
+					Percentage: models.NewPercentage(110),
+				},
+			},
+			ExpectedError: true,
+		},
+		{
+			Name: "Valid - usage",
+			Discounts: Discounts{
+				Usage: &UsageDiscount{
+					Quantity: decimal.NewFromInt(100),
+				},
+			},
+			ExpectedError: false,
+		},
+		{
+			Name: "Invalid - usage - negative",
+			Discounts: Discounts{
+				Usage: &UsageDiscount{
+					Quantity: decimal.NewFromInt(-100),
+				},
+			},
+			ExpectedError: true,
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.Name, func(t *testing.T) {
+			err := test.Discounts.ValidateForPrice(NewPriceFrom(
+				UnitPrice{
+					Amount: decimal.NewFromInt(100),
+				},
+			))
+			if test.ExpectedError {
+				require.Error(t, err)
+			} else {
+				require.NoError(t, err)
+			}
+		})
+	}
+}

openmeter/productcatalog/driver/errors.go

@@ -0,0 +1,24 @@
+package productcatalogdriver
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport/encoder"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+)
+
+func getErrorEncoder() encoder.ErrorEncoder {
+	return func(ctx context.Context, err error, w http.ResponseWriter, r *http.Request) bool {
+		return commonhttp.HandleErrorIfTypeMatches[*feature.FeatureNotFoundError](ctx, http.StatusNotFound, err, w) ||
+			commonhttp.HandleErrorIfTypeMatches[*feature.FeatureInvalidFiltersError](ctx, http.StatusBadRequest, err, w) ||
+			commonhttp.HandleErrorIfTypeMatches[*feature.ForbiddenError](ctx, http.StatusBadRequest, err, w) ||
+			commonhttp.HandleErrorIfTypeMatches[*pagination.InvalidError](ctx, http.StatusBadRequest, err, w) ||
+			commonhttp.HandleErrorIfTypeMatches[*feature.FeatureInvalidMeterAggregationError](ctx, http.StatusBadRequest, err, w) ||
+			commonhttp.HandleErrorIfTypeMatches[*meter.MeterNotFoundError](ctx, http.StatusNotFound, err, w) ||
+			commonhttp.HandleErrorIfTypeMatches[*feature.FeatureWithNameAlreadyExistsError](ctx, http.StatusConflict, err, w)
+	}
+}

openmeter/productcatalog/driver/feature.go

@@ -0,0 +1,291 @@
+package productcatalogdriver
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+
+	"github.com/samber/lo"
+
+	"github.com/openmeterio/openmeter/api"
+	"github.com/openmeterio/openmeter/openmeter/llmcost"
+	"github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/openmeter/namespace/namespacedriver"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	"github.com/openmeterio/openmeter/pkg/convert"
+	"github.com/openmeterio/openmeter/pkg/defaultx"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/operation"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+	"github.com/openmeterio/openmeter/pkg/sortx"
+	"github.com/openmeterio/openmeter/pkg/strcase"
+)
+
+type FeatureHandler interface {
+	GetFeature() GetFeatureHandler
+	CreateFeature() CreateFeatureHandler
+	ListFeatures() ListFeaturesHandler
+	DeleteFeature() DeleteFeatureHandler
+}
+
+type featureHandlers struct {
+	namespaceDecoder namespacedriver.NamespaceDecoder
+	options          []httptransport.HandlerOption
+	connector        feature.FeatureConnector
+	meterService     meter.Service
+	llmcostService   llmcost.Service
+}
+
+func NewFeatureHandler(
+	connector feature.FeatureConnector,
+	namespaceDecoder namespacedriver.NamespaceDecoder,
+	meterService meter.Service,
+	llmcostService llmcost.Service,
+	options ...httptransport.HandlerOption,
+) FeatureHandler {
+	return &featureHandlers{
+		namespaceDecoder: namespaceDecoder,
+		options:          options,
+		connector:        connector,
+		meterService:     meterService,
+		llmcostService:   llmcostService,
+	}
+}
+
+type (
+	GetFeatureHandlerRequest  = models.NamespacedID
+	GetFeatureHandlerResponse = api.Feature
+	GetFeatureHandlerParams   = string
+)
+
+type GetFeatureHandler httptransport.HandlerWithArgs[GetFeatureHandlerRequest, GetFeatureHandlerResponse, GetFeatureHandlerParams]
+
+func (h *featureHandlers) GetFeature() GetFeatureHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, featureID string) (GetFeatureHandlerRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return models.NamespacedID{}, err
+			}
+
+			return models.NamespacedID{
+				Namespace: ns,
+				ID:        featureID,
+			}, nil
+		},
+		func(ctx context.Context, featureId GetFeatureHandlerRequest) (GetFeatureHandlerResponse, error) {
+			feat, err := h.connector.GetFeature(ctx, featureId.Namespace, featureId.ID, feature.IncludeArchivedFeatureFalse)
+			if err != nil {
+				return api.Feature{}, err
+			}
+
+			resp, err := MapFeatureToResponse(*feat)
+			if err != nil {
+				return api.Feature{}, err
+			}
+
+			// Resolve LLM pricing if the feature has LLM unit cost
+			if feat.UnitCost != nil && feat.UnitCost.Type == feature.UnitCostTypeLLM && h.llmcostService != nil {
+				pricing := resolveLLMPricing(ctx, h.llmcostService, feat)
+				if pricing != nil {
+					enrichFeatureResponseWithPricing(&resp, pricing)
+				}
+			}
+
+			return resp, nil
+		},
+		commonhttp.JSONResponseEncoder,
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithErrorEncoder(getErrorEncoder()),
+			httptransport.WithOperationName("getFeature"),
+		)...,
+	)
+}
+
+type (
+	CreateFeatureHandlerRequest  = feature.CreateFeatureInputs
+	CreateFeatureHandlerResponse = api.Feature
+)
+
+type CreateFeatureHandler httptransport.Handler[CreateFeatureHandlerRequest, CreateFeatureHandlerResponse]
+
+func (h *featureHandlers) CreateFeature() CreateFeatureHandler {
+	return httptransport.NewHandler(
+		func(ctx context.Context, r *http.Request) (feature.CreateFeatureInputs, error) {
+			parsedBody := api.CreateFeatureJSONRequestBody{}
+			emptyFeature := feature.CreateFeatureInputs{}
+			if err := commonhttp.JSONRequestBodyDecoder(r, &parsedBody); err != nil {
+				return emptyFeature, err
+			}
+
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return emptyFeature, err
+			}
+
+			// Resolve meter slug to meter ID
+			var meterID *string
+			if parsedBody.MeterSlug != nil {
+				m, err := h.meterService.GetMeterByIDOrSlug(ctx, meter.GetMeterInput{
+					Namespace: ns,
+					IDOrSlug:  *parsedBody.MeterSlug,
+				})
+				if err != nil {
+					return emptyFeature, err
+				}
+				meterID = &m.ID
+			}
+
+			return MapFeatureCreateInputsRequest(ns, parsedBody, meterID)
+		},
+		func(ctx context.Context, feature feature.CreateFeatureInputs) (api.Feature, error) {
+			createdFeature, err := h.connector.CreateFeature(ctx, feature)
+			if err != nil {
+				return api.Feature{}, err
+			}
+			return MapFeatureToResponse(createdFeature)
+		},
+		commonhttp.JSONResponseEncoderWithStatus[api.Feature](http.StatusCreated),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("createFeature"),
+			httptransport.WithErrorEncoder(getErrorEncoder()),
+		)...,
+	)
+}
+
+type (
+	ListFeaturesHandlerRequest  = feature.ListFeaturesParams
+	ListFeaturesHandlerResponse = commonhttp.Union[[]api.Feature, pagination.Result[api.Feature]]
+	ListFeaturesHandlerParams   = api.ListFeaturesParams
+)
+
+type ListFeaturesHandler httptransport.HandlerWithArgs[ListFeaturesHandlerRequest, ListFeaturesHandlerResponse, ListFeaturesHandlerParams]
+
+func (h *featureHandlers) ListFeatures() ListFeaturesHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, apiParams ListFeaturesHandlerParams) (ListFeaturesHandlerRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return feature.ListFeaturesParams{}, err
+			}
+
+			params := feature.ListFeaturesParams{
+				Namespace:       ns,
+				IncludeArchived: defaultx.WithDefault(apiParams.IncludeArchived, false),
+				Page: pagination.Page{
+					PageSize:   defaultx.WithDefault(apiParams.PageSize, 0),
+					PageNumber: defaultx.WithDefault(apiParams.Page, 0),
+				},
+				Limit:  defaultx.WithDefault(apiParams.Limit, commonhttp.DefaultPageSize),
+				Offset: defaultx.WithDefault(apiParams.Offset, 0),
+				OrderBy: feature.FeatureOrderBy(
+					// Go enum value has a snake_case name, so we need to convert it
+					strcase.CamelToSnake(string(lo.FromPtrOr(apiParams.OrderBy, api.FeatureOrderByKey))),
+				),
+				Order:      sortx.Order(lo.FromPtrOr(apiParams.Order, api.SortOrderASC)),
+				MeterSlugs: convert.DerefHeaderPtr[string](apiParams.MeterSlug),
+			}
+
+			if !params.Page.IsZero() {
+				params.Page.PageNumber = defaultx.IfZero(params.Page.PageNumber, commonhttp.DefaultPage)
+				params.Page.PageSize = defaultx.IfZero(params.Page.PageSize, commonhttp.DefaultPageSize)
+			}
+
+			// TODO: standardize
+			if params.Page.PageSize > 1000 {
+				return params, commonhttp.NewHTTPError(
+					http.StatusBadRequest,
+					fmt.Errorf("limit must be less than or equal to %d", 1000),
+				)
+			}
+
+			return params, nil
+		},
+		func(ctx context.Context, params ListFeaturesHandlerRequest) (ListFeaturesHandlerResponse, error) {
+			response := ListFeaturesHandlerResponse{
+				Option1: &[]api.Feature{},
+				Option2: &pagination.Result[api.Feature]{},
+			}
+
+			paged, err := h.connector.ListFeatures(ctx, params)
+			if err != nil {
+				return response, err
+			}
+
+			mapped := make([]api.Feature, 0, len(paged.Items))
+			for _, f := range paged.Items {
+				resp, err := MapFeatureToResponse(f)
+				if err != nil {
+					return response, err
+				}
+				mapped = append(mapped, resp)
+			}
+
+			if params.Page.IsZero() {
+				response.Option1 = &mapped
+			} else {
+				response.Option1 = nil
+				response.Option2 = &pagination.Result[api.Feature]{
+					Items:      mapped,
+					TotalCount: paged.TotalCount,
+					Page:       paged.Page,
+				}
+			}
+
+			return response, err
+		},
+		commonhttp.JSONResponseEncoder,
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("listFeatures"),
+		)...,
+	)
+}
+
+type (
+	DeleteFeatureHandlerRequest  = models.NamespacedID
+	DeleteFeatureHandlerResponse = interface{}
+	DeleteFeatureHandlerParams   = string
+)
+
+type DeleteFeatureHandler httptransport.HandlerWithArgs[DeleteFeatureHandlerRequest, DeleteFeatureHandlerResponse, DeleteFeatureHandlerParams]
+
+func (h *featureHandlers) DeleteFeature() DeleteFeatureHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, featureID DeleteFeatureHandlerParams) (DeleteFeatureHandlerRequest, error) {
+			id := models.NamespacedID{
+				ID: featureID,
+			}
+
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return id, err
+			}
+
+			id.Namespace = ns
+
+			return id, nil
+		},
+		operation.AsNoResponseOperation(h.connector.ArchiveFeature),
+		commonhttp.EmptyResponseEncoder[DeleteFeatureHandlerResponse](http.StatusNoContent),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("deleteFeature"),
+			httptransport.WithErrorEncoder(getErrorEncoder()),
+		)...,
+	)
+}
+
+func (h *featureHandlers) resolveNamespace(ctx context.Context) (string, error) {
+	ns, ok := h.namespaceDecoder.GetNamespace(ctx)
+	if !ok {
+		return "", commonhttp.NewHTTPError(http.StatusInternalServerError, errors.New("internal server error"))
+	}
+
+	return ns, nil
+}

openmeter/productcatalog/driver/parser.go

@@ -0,0 +1,247 @@
+package productcatalogdriver
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/alpacahq/alpacadecimal"
+	"github.com/samber/lo"
+
+	"github.com/openmeterio/openmeter/api"
+	"github.com/openmeterio/openmeter/openmeter/apiconverter"
+	"github.com/openmeterio/openmeter/openmeter/llmcost"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	"github.com/openmeterio/openmeter/pkg/convert"
+	"github.com/openmeterio/openmeter/pkg/filter"
+)
+
+func MapFeatureToResponse(f feature.Feature) (api.Feature, error) {
+	meterGroupByFilters := feature.ConvertMeterGroupByFiltersToMapString(f.MeterGroupByFilters)
+
+	resp := api.Feature{
+		CreatedAt:                   f.CreatedAt,
+		DeletedAt:                   nil,
+		UpdatedAt:                   f.UpdatedAt,
+		Id:                          f.ID,
+		Key:                         f.Key,
+		Metadata:                    convert.MapToPointer(f.Metadata),
+		Name:                        f.Name,
+		ArchivedAt:                  f.ArchivedAt,
+		MeterGroupByFilters:         convert.MapToPointer(meterGroupByFilters),
+		AdvancedMeterGroupByFilters: convert.MapToPointer(apiconverter.ConvertStringMapToAPIPtr(f.MeterGroupByFilters)),
+		MeterSlug:                   f.MeterSlug,
+	}
+
+	if f.UnitCost != nil {
+		apiUnitCost, err := domainUnitCostToAPI(f.UnitCost)
+		if err != nil {
+			return api.Feature{}, fmt.Errorf("failed to convert unit cost: %w", err)
+		}
+		resp.UnitCost = &apiUnitCost
+	}
+
+	return resp, nil
+}
+
+func MapFeatureCreateInputsRequest(namespace string, f api.FeatureCreateInputs, meterID *string) (feature.CreateFeatureInputs, error) {
+	// if advancedMeterGroupByFilters is set, use it
+	// otherwise, use legacy meterGroupByFilters
+	meterGroupByFilters := lo.FromPtrOr(apiconverter.ConvertStringMapPtr(f.AdvancedMeterGroupByFilters), map[string]filter.FilterString{})
+	if len(meterGroupByFilters) == 0 {
+		meterGroupByFilters = feature.ConvertMapStringToMeterGroupByFilters(lo.FromPtrOr(f.MeterGroupByFilters, map[string]string{}))
+	}
+
+	inputs := feature.CreateFeatureInputs{
+		Namespace:           namespace,
+		Name:                f.Name,
+		Key:                 f.Key,
+		MeterID:             meterID,
+		MeterGroupByFilters: meterGroupByFilters,
+		Metadata:            convert.DerefHeaderPtr[string](f.Metadata),
+	}
+
+	if f.UnitCost != nil {
+		unitCost, err := apiUnitCostToDomain(f.UnitCost)
+		if err != nil {
+			return feature.CreateFeatureInputs{}, fmt.Errorf("invalid unit cost: %w", err)
+		}
+		inputs.UnitCost = unitCost
+	}
+
+	return inputs, nil
+}
+
+func domainUnitCostToAPI(u *feature.UnitCost) (api.FeatureUnitCost, error) {
+	var out api.FeatureUnitCost
+
+	switch u.Type {
+	case feature.UnitCostTypeManual:
+		if err := out.FromFeatureManualUnitCost(api.FeatureManualUnitCost{
+			Amount: u.Manual.Amount.String(),
+		}); err != nil {
+			return out, fmt.Errorf("failed to convert manual unit cost: %w", err)
+		}
+	case feature.UnitCostTypeLLM:
+		llmCost := api.FeatureLLMUnitCost{}
+		if u.LLM.ProviderProperty != "" {
+			llmCost.ProviderProperty = lo.ToPtr(u.LLM.ProviderProperty)
+		}
+		if u.LLM.Provider != "" {
+			llmCost.Provider = lo.ToPtr(u.LLM.Provider)
+		}
+		if u.LLM.ModelProperty != "" {
+			llmCost.ModelProperty = lo.ToPtr(u.LLM.ModelProperty)
+		}
+		if u.LLM.Model != "" {
+			llmCost.Model = lo.ToPtr(u.LLM.Model)
+		}
+		if u.LLM.TokenTypeProperty != "" {
+			llmCost.TokenTypeProperty = lo.ToPtr(u.LLM.TokenTypeProperty)
+		}
+		if u.LLM.TokenType != "" {
+			llmCost.TokenType = lo.ToPtr(u.LLM.TokenType)
+		}
+		if err := out.FromFeatureLLMUnitCost(llmCost); err != nil {
+			return out, fmt.Errorf("failed to convert LLM unit cost: %w", err)
+		}
+	default:
+		return out, fmt.Errorf("unknown unit cost type: %s", u.Type)
+	}
+
+	return out, nil
+}
+
+func apiUnitCostToDomain(u *api.FeatureUnitCost) (*feature.UnitCost, error) {
+	discriminator, err := u.Discriminator()
+	if err != nil {
+		return nil, fmt.Errorf("failed to determine unit cost type: %w", err)
+	}
+
+	switch discriminator {
+	case "manual":
+		manual, err := u.AsFeatureManualUnitCost()
+		if err != nil {
+			return nil, fmt.Errorf("failed to parse manual unit cost: %w", err)
+		}
+
+		amount, err := alpacadecimal.NewFromString(manual.Amount)
+		if err != nil {
+			return nil, fmt.Errorf("invalid manual unit cost amount %q: %w", manual.Amount, err)
+		}
+
+		return &feature.UnitCost{
+			Type: feature.UnitCostTypeManual,
+			Manual: &feature.ManualUnitCost{
+				Amount: amount,
+			},
+		}, nil
+	case "llm":
+		llm, err := u.AsFeatureLLMUnitCost()
+		if err != nil {
+			return nil, fmt.Errorf("failed to parse LLM unit cost: %w", err)
+		}
+
+		return &feature.UnitCost{
+			Type: feature.UnitCostTypeLLM,
+			LLM: &feature.LLMUnitCost{
+				ProviderProperty:  lo.FromPtrOr(llm.ProviderProperty, ""),
+				Provider:          lo.FromPtrOr(llm.Provider, ""),
+				ModelProperty:     lo.FromPtrOr(llm.ModelProperty, ""),
+				Model:             lo.FromPtrOr(llm.Model, ""),
+				TokenTypeProperty: lo.FromPtrOr(llm.TokenTypeProperty, ""),
+				TokenType:         lo.FromPtrOr(llm.TokenType, ""),
+			},
+		}, nil
+	default:
+		return nil, fmt.Errorf("unknown unit cost type: %s", discriminator)
+	}
+}
+
+// resolveLLMPricing extracts provider and model from the feature's meterGroupByFilters
+// and resolves the current pricing from the LLM cost database.
+// Returns nil if provider/model can't be determined or pricing can't be resolved.
+func resolveLLMPricing(ctx context.Context, svc llmcost.Service, feat *feature.Feature) *llmcost.ModelPricing {
+	if feat.UnitCost == nil || feat.UnitCost.LLM == nil {
+		return nil
+	}
+
+	llmConf := feat.UnitCost.LLM
+
+	// Resolve provider: static value or from meterGroupByFilters
+	provider := llmConf.Provider
+	if provider == "" {
+		provider = extractEqFilterValue(feat.MeterGroupByFilters, llmConf.ProviderProperty)
+	}
+	if provider == "" {
+		return nil
+	}
+
+	// Resolve model: static value or from meterGroupByFilters
+	model := llmConf.Model
+	if model == "" {
+		model = extractEqFilterValue(feat.MeterGroupByFilters, llmConf.ModelProperty)
+	}
+	if model == "" {
+		return nil
+	}
+
+	price, err := svc.ResolvePrice(ctx, llmcost.ResolvePriceInput{
+		Namespace: feat.Namespace,
+		Provider:  llmcost.Provider(provider),
+		ModelID:   model,
+	})
+	if err != nil {
+		return nil
+	}
+
+	return &price.Pricing
+}
+
+// extractEqFilterValue extracts a simple $eq value from a MeterGroupByFilters map for the given key.
+func extractEqFilterValue(filters feature.MeterGroupByFilters, key string) string {
+	if filters == nil {
+		return ""
+	}
+
+	f, ok := filters[key]
+	if !ok || f.Eq == nil {
+		return ""
+	}
+
+	return *f.Eq
+}
+
+// enrichFeatureResponseWithPricing adds resolved LLM pricing to the feature API response.
+func enrichFeatureResponseWithPricing(resp *api.Feature, pricing *llmcost.ModelPricing) {
+	if resp.UnitCost == nil || pricing == nil {
+		return
+	}
+
+	llmCost, err := resp.UnitCost.AsFeatureLLMUnitCost()
+	if err != nil {
+		return
+	}
+
+	apiPricing := api.FeatureLLMUnitCostPricing{
+		InputPerToken:  pricing.InputPerToken.String(),
+		OutputPerToken: pricing.OutputPerToken.String(),
+	}
+
+	if pricing.CacheReadPerToken != nil {
+		v := pricing.CacheReadPerToken.String()
+		apiPricing.CacheReadPerToken = &v
+	}
+
+	if pricing.CacheWritePerToken != nil {
+		v := pricing.CacheWritePerToken.String()
+		apiPricing.CacheWritePerToken = &v
+	}
+
+	if pricing.ReasoningPerToken != nil {
+		v := pricing.ReasoningPerToken.String()
+		apiPricing.ReasoningPerToken = &v
+	}
+
+	llmCost.Pricing = &apiPricing
+	_ = resp.UnitCost.FromFeatureLLMUnitCost(llmCost)
+}

openmeter/productcatalog/effectiveperiod.go

@@ -0,0 +1,74 @@
+package productcatalog
+
+import (
+	"errors"
+	"time"
+
+	"github.com/samber/lo"
+
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/timeutil"
+)
+
+var (
+	_ models.Validator                        = (*EffectivePeriod)(nil)
+	_ models.Equaler[EffectivePeriod]         = (*EffectivePeriod)(nil)
+	_ models.CustomValidator[EffectivePeriod] = (*EffectivePeriod)(nil)
+)
+
+// EffectivePeriod describes lifecycle of resource based on the time period defined by it.
+type EffectivePeriod struct {
+	// EffectiveFrom defines the time from the Plan or Addon becomes active.
+	EffectiveFrom *time.Time `json:"effectiveFrom,omitempty"`
+
+	// EffectiveTo defines the time from the Plan or Addon becomes archived.
+	EffectiveTo *time.Time `json:"effectiveTo,omitempty"`
+}
+
+func (p EffectivePeriod) ValidateWith(v ...models.ValidatorFunc[EffectivePeriod]) error {
+	return models.Validate(p, v...)
+}
+
+func (p EffectivePeriod) AsPeriod() timeutil.OpenPeriod {
+	return timeutil.OpenPeriod{
+		From: p.EffectiveFrom,
+		To:   p.EffectiveTo,
+	}
+}
+
+func (p EffectivePeriod) Validate() error {
+	return p.ValidateWith(ValidateEffectivePeriod())
+}
+
+func ValidateEffectivePeriod() models.ValidatorFunc[EffectivePeriod] {
+	return func(p EffectivePeriod) error {
+		var errs []error
+
+		from := lo.FromPtr(p.EffectiveFrom)
+		to := lo.FromPtr(p.EffectiveTo)
+
+		if !from.IsZero() && !to.IsZero() && from.After(to) {
+			errs = append(errs, ErrEffectivePeriodFromAfterTo.
+				WithAttrs(models.Attributes{
+					"effectiveFrom": p.EffectiveFrom,
+					"effectiveTo":   p.EffectiveTo,
+				}))
+		}
+
+		if from.IsZero() && !to.IsZero() {
+			errs = append(errs, ErrEffectivePeriodFromNotSet.
+				WithAttrs(models.Attributes{
+					"effectiveFrom": nil,
+					"effectiveTo":   p.EffectiveTo,
+				}))
+		}
+
+		return errors.Join(errs...)
+	}
+}
+
+// Equal returns true if the two EffectivePeriod objects are equal.
+func (p EffectivePeriod) Equal(o EffectivePeriod) bool {
+	return lo.FromPtr(p.EffectiveFrom).Equal(lo.FromPtr(o.EffectiveFrom)) &&
+		lo.FromPtr(p.EffectiveTo).Equal(lo.FromPtr(o.EffectiveTo))
+}

openmeter/productcatalog/effectiveperiod_test.go

@@ -0,0 +1,147 @@
+package productcatalog
+
+import (
+	"testing"
+	"time"
+
+	"github.com/samber/lo"
+	"github.com/stretchr/testify/assert"
+
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+func TestEffectivePeriod_Validate(t *testing.T) {
+	now := time.Now()
+	yesterday := now.Add(-24 * time.Hour)
+
+	tests := []struct {
+		Name string
+
+		EffectivePeriod          EffectivePeriod
+		ExpectedError            bool
+		ExpectedValidationIssues models.ValidationIssues
+	}{
+		{
+			Name: "Valid/Zero",
+			EffectivePeriod: EffectivePeriod{
+				EffectiveFrom: nil,
+				EffectiveTo:   nil,
+			},
+			ExpectedError: false,
+		},
+		{
+			Name: "Valid/OpenEnded",
+			EffectivePeriod: EffectivePeriod{
+				EffectiveFrom: lo.ToPtr(yesterday),
+				EffectiveTo:   nil,
+			},
+			ExpectedError: false,
+		},
+		{
+			Name: "Valid/Range",
+			EffectivePeriod: EffectivePeriod{
+				EffectiveFrom: lo.ToPtr(yesterday),
+				EffectiveTo:   lo.ToPtr(now),
+			},
+			ExpectedError: false,
+		},
+		{
+			Name: "Invalid/Flipped",
+			EffectivePeriod: EffectivePeriod{
+				EffectiveFrom: lo.ToPtr(now),
+				EffectiveTo:   lo.ToPtr(yesterday),
+			},
+			ExpectedError: true,
+			ExpectedValidationIssues: models.ValidationIssues{
+				ErrEffectivePeriodFromAfterTo.WithAttrs(models.Attributes{
+					"effectiveFrom": lo.ToPtr(now),
+					"effectiveTo":   lo.ToPtr(yesterday),
+				}),
+			},
+		},
+		{
+			Name: "Invalid/OpenStart",
+			EffectivePeriod: EffectivePeriod{
+				EffectiveFrom: nil,
+				EffectiveTo:   lo.ToPtr(now),
+			},
+			ExpectedError: true,
+			ExpectedValidationIssues: models.ValidationIssues{
+				ErrEffectivePeriodFromNotSet.WithAttrs(models.Attributes{
+					"effectiveFrom": nil,
+					"effectiveTo":   lo.ToPtr(now),
+				}),
+			},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.Name, func(t *testing.T) {
+			if test.ExpectedError {
+				err := test.EffectivePeriod.Validate()
+				assert.Errorf(t, err, "expected invalid effective period")
+
+				issues, err := models.AsValidationIssues(err)
+				assert.NoError(t, err)
+
+				models.RequireValidationIssuesMatch(t, test.ExpectedValidationIssues, issues)
+			} else {
+				assert.NoErrorf(t, test.EffectivePeriod.Validate(), "expected valid effective period")
+			}
+		})
+	}
+}
+
+func TestEffectivePeriod_Equal(t *testing.T) {
+	tests := []struct {
+		Name string
+
+		Left     EffectivePeriod
+		Right    EffectivePeriod
+		Expected bool
+	}{
+		{
+			Name: "Equal/Nil",
+			Left: EffectivePeriod{
+				EffectiveFrom: nil,
+				EffectiveTo:   nil,
+			},
+			Right: EffectivePeriod{
+				EffectiveFrom: nil,
+				EffectiveTo:   nil,
+			},
+			Expected: true,
+		},
+		{
+			Name: "Equal/ZeroNil",
+			Left: EffectivePeriod{
+				EffectiveFrom: lo.ToPtr(time.Time{}),
+				EffectiveTo:   lo.ToPtr(time.Time{}),
+			},
+			Right: EffectivePeriod{
+				EffectiveFrom: nil,
+				EffectiveTo:   nil,
+			},
+			Expected: true,
+		},
+		{
+			Name: "Valid/Zero",
+			Left: EffectivePeriod{
+				EffectiveFrom: lo.ToPtr(time.Time{}),
+				EffectiveTo:   lo.ToPtr(time.Time{}),
+			},
+			Right: EffectivePeriod{
+				EffectiveFrom: lo.ToPtr(time.Time{}),
+				EffectiveTo:   lo.ToPtr(time.Time{}),
+			},
+			Expected: true,
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.Name, func(t *testing.T) {
+			eq := test.Left.Equal(test.Right)
+			assert.Equalf(t, test.Expected, eq, "expected %v, got %v", test.Expected, eq)
+		})
+	}
+}

openmeter/productcatalog/entitlement.go

@@ -0,0 +1,422 @@
+package productcatalog
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+
+	"github.com/samber/lo"
+
+	"github.com/openmeterio/openmeter/openmeter/entitlement"
+	"github.com/openmeterio/openmeter/pkg/datetime"
+	"github.com/openmeterio/openmeter/pkg/hasher"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+type entitlementTemplater interface {
+	json.Marshaler
+	json.Unmarshaler
+	models.Validator
+	models.Equaler[*EntitlementTemplate]
+
+	Type() entitlement.EntitlementType
+	AsMetered() (MeteredEntitlementTemplate, error)
+	AsStatic() (StaticEntitlementTemplate, error)
+	AsBoolean() (BooleanEntitlementTemplate, error)
+	FromMetered(MeteredEntitlementTemplate)
+	FromStatic(StaticEntitlementTemplate)
+	FromBoolean(BooleanEntitlementTemplate)
+}
+
+var _ entitlementTemplater = (*EntitlementTemplate)(nil)
+
+// EntitlementTemplate is the template used for instantiating entitlement.Entitlement for RateCard.
+type EntitlementTemplate struct {
+	t       entitlement.EntitlementType
+	metered *MeteredEntitlementTemplate
+	static  *StaticEntitlementTemplate
+	boolean *BooleanEntitlementTemplate
+}
+
+func (e *EntitlementTemplate) Equal(v *EntitlementTemplate) bool {
+	if e == nil && v == nil {
+		return true
+	}
+
+	if e == nil || v == nil {
+		return false
+	}
+
+	if e.t != v.t {
+		return false
+	}
+
+	switch e.t {
+	case entitlement.EntitlementTypeMetered:
+		return e.metered.Equal(v.metered)
+	case entitlement.EntitlementTypeStatic:
+		return e.static.Equal(v.static)
+	case entitlement.EntitlementTypeBoolean:
+		return e.boolean.Equal(v.boolean)
+	default:
+		return false
+	}
+}
+
+func (e *EntitlementTemplate) MarshalJSON() ([]byte, error) {
+	var b []byte
+	var err error
+	var serde interface{}
+
+	switch e.t {
+	case entitlement.EntitlementTypeMetered:
+		serde = struct {
+			Type entitlement.EntitlementType `json:"type"`
+			*MeteredEntitlementTemplate
+		}{
+			Type:                       entitlement.EntitlementTypeMetered,
+			MeteredEntitlementTemplate: e.metered,
+		}
+	case entitlement.EntitlementTypeStatic:
+		serde = struct {
+			Type entitlement.EntitlementType `json:"type"`
+			*StaticEntitlementTemplate
+		}{
+			Type:                      entitlement.EntitlementTypeStatic,
+			StaticEntitlementTemplate: e.static,
+		}
+	case entitlement.EntitlementTypeBoolean:
+		serde = struct {
+			Type entitlement.EntitlementType `json:"type"`
+			*BooleanEntitlementTemplate
+		}{
+			Type:                       entitlement.EntitlementTypeBoolean,
+			BooleanEntitlementTemplate: e.boolean,
+		}
+	default:
+		return nil, fmt.Errorf("invalid Entitlement type: %s", e.t)
+	}
+
+	b, err = json.Marshal(serde)
+	if err != nil {
+		return nil, fmt.Errorf("failed to JSON serialize EntitlementTemplate: %w", err)
+	}
+
+	return b, nil
+}
+
+func (e *EntitlementTemplate) UnmarshalJSON(bytes []byte) error {
+	serde := struct {
+		Type entitlement.EntitlementType `json:"type"`
+	}{}
+
+	if err := json.Unmarshal(bytes, &serde); err != nil {
+		return fmt.Errorf("failed to JSON deserialize EntitlementTemplate type: %w", err)
+	}
+
+	switch serde.Type {
+	case entitlement.EntitlementTypeMetered:
+		v := &MeteredEntitlementTemplate{}
+		if err := json.Unmarshal(bytes, v); err != nil {
+			return fmt.Errorf("failed to JSON deserialize EntitlementTemplate: %w", err)
+		}
+
+		e.metered = v
+		e.t = entitlement.EntitlementTypeMetered
+	case entitlement.EntitlementTypeStatic:
+		v := &StaticEntitlementTemplate{}
+		if err := json.Unmarshal(bytes, v); err != nil {
+			return fmt.Errorf("failed to JSON deserialize EntitlementTemplate: %w", err)
+		}
+
+		e.static = v
+		e.t = entitlement.EntitlementTypeStatic
+	case entitlement.EntitlementTypeBoolean:
+		v := &BooleanEntitlementTemplate{}
+		if err := json.Unmarshal(bytes, v); err != nil {
+			return fmt.Errorf("failed to JSON deserialize EntitlementTemplate: %w", err)
+		}
+
+		e.boolean = v
+		e.t = entitlement.EntitlementTypeBoolean
+	default:
+		return fmt.Errorf("invalid EntitlementTemplate type: %s", serde.Type)
+	}
+
+	return nil
+}
+
+func (e *EntitlementTemplate) Validate() error {
+	if e == nil {
+		return nil
+	}
+
+	switch e.t {
+	case entitlement.EntitlementTypeMetered:
+		return e.metered.Validate()
+	case entitlement.EntitlementTypeStatic:
+		return e.static.Validate()
+	case entitlement.EntitlementTypeBoolean:
+		return e.boolean.Validate()
+	default:
+		return fmt.Errorf("invalid entitlement template type: %q", e.t)
+	}
+}
+
+func (e *EntitlementTemplate) Type() entitlement.EntitlementType {
+	return e.t
+}
+
+func (e *EntitlementTemplate) AsMetered() (MeteredEntitlementTemplate, error) {
+	switch e.t {
+	case entitlement.EntitlementTypeMetered:
+		if e.metered == nil {
+			return MeteredEntitlementTemplate{}, errors.New("invalid metered entitlement template: not initialized")
+		}
+
+		return *e.metered, nil
+	case entitlement.EntitlementTypeBoolean, entitlement.EntitlementTypeStatic:
+		return MeteredEntitlementTemplate{}, fmt.Errorf("invalid entitlement template: type mismatch: %s", e.t)
+	default:
+		return MeteredEntitlementTemplate{}, errors.New("invalid entitlement template: not initialized")
+	}
+}
+
+func (e *EntitlementTemplate) AsStatic() (StaticEntitlementTemplate, error) {
+	switch e.t {
+	case entitlement.EntitlementTypeStatic:
+		if e.static == nil {
+			return StaticEntitlementTemplate{}, errors.New("invalid static entitlement template: not initialized")
+		}
+
+		return *e.static, nil
+	case entitlement.EntitlementTypeBoolean, entitlement.EntitlementTypeMetered:
+		return StaticEntitlementTemplate{}, fmt.Errorf("invalid entitlement template: type mismatch: %s", e.t)
+	default:
+		return StaticEntitlementTemplate{}, errors.New("invalid entitlement template: not initialized")
+	}
+}
+
+func (e *EntitlementTemplate) AsBoolean() (BooleanEntitlementTemplate, error) {
+	switch e.t {
+	case entitlement.EntitlementTypeBoolean:
+		if e.boolean == nil {
+			return BooleanEntitlementTemplate{}, errors.New("invalid boolean entitlement template: not initialized")
+		}
+
+		return *e.boolean, nil
+	case entitlement.EntitlementTypeStatic, entitlement.EntitlementTypeMetered:
+		return BooleanEntitlementTemplate{}, fmt.Errorf("invalid entitlement template: type mismatch: %s", e.t)
+	default:
+		return BooleanEntitlementTemplate{}, errors.New("invalid entitlement template: not initialized")
+	}
+}
+
+func (e *EntitlementTemplate) FromMetered(t MeteredEntitlementTemplate) {
+	e.metered = &t
+	e.t = entitlement.EntitlementTypeMetered
+}
+
+func (e *EntitlementTemplate) FromStatic(t StaticEntitlementTemplate) {
+	e.static = &t
+	e.t = entitlement.EntitlementTypeStatic
+}
+
+func (e *EntitlementTemplate) FromBoolean(t BooleanEntitlementTemplate) {
+	e.boolean = &t
+	e.t = entitlement.EntitlementTypeBoolean
+}
+
+func NewEntitlementTemplateFrom[T MeteredEntitlementTemplate | StaticEntitlementTemplate | BooleanEntitlementTemplate](c T) *EntitlementTemplate {
+	r := &EntitlementTemplate{}
+
+	switch any(c).(type) {
+	case MeteredEntitlementTemplate:
+		e := any(c).(MeteredEntitlementTemplate)
+		r.FromMetered(e)
+	case StaticEntitlementTemplate:
+		e := any(c).(StaticEntitlementTemplate)
+		r.FromStatic(e)
+	case BooleanEntitlementTemplate:
+		e := any(c).(BooleanEntitlementTemplate)
+		r.FromBoolean(e)
+	}
+
+	return r
+}
+
+var (
+	_ models.Validator                            = (*MeteredEntitlementTemplate)(nil)
+	_ models.Equaler[*MeteredEntitlementTemplate] = (*MeteredEntitlementTemplate)(nil)
+)
+
+type MeteredEntitlementTemplate struct {
+	// Metadata a set of key/value pairs describing metadata for the RateCard.
+	Metadata models.Metadata `json:"metadata,omitempty"`
+
+	// IsSoftLimit set to `true` for allowing the subject to use the feature even if the entitlement is exhausted.
+	IsSoftLimit bool `json:"isSoftLimit,omitempty"`
+
+	// IssueAfterReset defines the amount to be automatically granted at entitlement.Entitlement creation or reset.
+	IssueAfterReset *float64 `json:"issueAfterReset,omitempty"`
+
+	// IssueAfterResetPriority defines the grant priority for the default grant.
+	IssueAfterResetPriority *uint8 `json:"issueAfterResetPriority,omitempty"`
+
+	// PreserveOverageAtReset defines whether the overage is preserved after reset.
+	PreserveOverageAtReset *bool `json:"preserveOverageAtReset,omitempty"`
+
+	// UsagePeriod defines the interval of the entitlement in ISO8601 format.
+	// Defaults to the billing cadence of the rate card.
+	// Example: "P1D12H"
+	UsagePeriod datetime.ISODuration `json:"usagePeriod,omitempty"`
+}
+
+func (t *MeteredEntitlementTemplate) Equal(v *MeteredEntitlementTemplate) bool {
+	if t == nil && v == nil {
+		return true
+	}
+
+	if t == nil || v == nil {
+		return false
+	}
+
+	if !t.Metadata.Equal(v.Metadata) {
+		return false
+	}
+
+	if !t.IsSoftLimit && v.IsSoftLimit {
+		return false
+	}
+
+	if (t.IssueAfterReset != nil && v.IssueAfterReset == nil) || (t.IssueAfterReset == nil && v.IssueAfterReset != nil) {
+		return false
+	}
+
+	if lo.FromPtr(t.IssueAfterReset) != lo.FromPtr(v.IssueAfterReset) {
+		return false
+	}
+
+	if (t.IssueAfterReset != nil && v.IssueAfterReset == nil) ||
+		(t.IssueAfterReset == nil && v.IssueAfterReset != nil) {
+		return false
+	}
+
+	if lo.FromPtr(t.IssueAfterReset) != lo.FromPtr(v.IssueAfterReset) {
+		return false
+	}
+
+	if (t.IssueAfterResetPriority != nil && v.IssueAfterResetPriority == nil) ||
+		(t.IssueAfterResetPriority == nil && v.IssueAfterResetPriority != nil) {
+		return false
+	}
+
+	if lo.FromPtr(t.IssueAfterResetPriority) != lo.FromPtr(v.IssueAfterResetPriority) {
+		return false
+	}
+
+	if (t.PreserveOverageAtReset != nil && v.PreserveOverageAtReset == nil) ||
+		(t.PreserveOverageAtReset == nil && v.PreserveOverageAtReset != nil) {
+		return false
+	}
+
+	if lo.FromPtr(t.PreserveOverageAtReset) != lo.FromPtr(v.PreserveOverageAtReset) {
+		return false
+	}
+
+	return t.UsagePeriod.ISOString() == v.UsagePeriod.ISOString()
+}
+
+func (t *MeteredEntitlementTemplate) Validate() error {
+	var errs []error
+
+	if t.IssueAfterResetPriority != nil && t.IssueAfterReset == nil {
+		errs = append(errs, ErrEntitlementTemplateInvalidIssueAfterResetWithPriority)
+	}
+
+	if t.UsagePeriod.Sign() != 1 {
+		errs = append(errs, ErrEntitlementTemplateNegativeUsagePeriod)
+	}
+
+	hour := datetime.NewISODuration(0, 0, 0, 0, 1, 0, 0)
+	if diff, err := t.UsagePeriod.Subtract(hour); err == nil && diff.Sign() == -1 {
+		errs = append(errs, ErrEntitlementTemplateUsagePeriodLessThenAnHour)
+	}
+
+	if err := errors.Join(errs...); err != nil {
+		return models.NewGenericValidationError(
+			models.ErrorWithFieldPrefix(
+				models.NewFieldSelectorGroup(models.NewFieldSelector("entitlementTemplate")),
+				err),
+		)
+	}
+
+	return nil
+}
+
+var (
+	_ models.Validator                           = (*StaticEntitlementTemplate)(nil)
+	_ models.Equaler[*StaticEntitlementTemplate] = (*StaticEntitlementTemplate)(nil)
+)
+
+type StaticEntitlementTemplate struct {
+	// Metadata a set of key/value pairs describing metadata for the RateCard.
+	Metadata models.Metadata `json:"metadata,omitempty"`
+
+	// Config stores a JSON parsable configuration for the entitlement.Entitlement.
+	// This value is also returned when checking entitlement access, and
+	// it is useful for configuring fine-grained access settings to the feature implemented in customers own system.
+	Config json.RawMessage `json:"config,omitempty"`
+}
+
+func (t *StaticEntitlementTemplate) Equal(v *StaticEntitlementTemplate) bool {
+	if t == nil && v == nil {
+		return true
+	}
+
+	if t == nil || v == nil {
+		return false
+	}
+
+	if !t.Metadata.Equal(v.Metadata) {
+		return false
+	}
+
+	return hasher.NewHash(t.Config) == hasher.NewHash(v.Config)
+}
+
+func (t *StaticEntitlementTemplate) Validate() error {
+	if len(t.Config) > 0 {
+		if ok := json.Valid(t.Config); !ok {
+			return models.NewGenericValidationError(ErrEntitlementTemplateInvalidJSONConfig)
+		}
+	}
+
+	return nil
+}
+
+var (
+	_ models.Validator                            = (*BooleanEntitlementTemplate)(nil)
+	_ models.Equaler[*BooleanEntitlementTemplate] = (*BooleanEntitlementTemplate)(nil)
+)
+
+type BooleanEntitlementTemplate struct {
+	// Metadata a set of key/value pairs describing metadata for the RateCard.
+	Metadata models.Metadata `json:"metadata,omitempty"`
+}
+
+func (t *BooleanEntitlementTemplate) Equal(v *BooleanEntitlementTemplate) bool {
+	if t == nil && v == nil {
+		return true
+	}
+
+	if t == nil || v == nil {
+		return false
+	}
+
+	return t.Metadata.Equal(v.Metadata)
+}
+
+func (t *BooleanEntitlementTemplate) Validate() error {
+	return nil
+}

openmeter/productcatalog/entitlement_test.go

@@ -0,0 +1,153 @@
+package productcatalog
+
+import (
+	"testing"
+
+	json "github.com/json-iterator/go"
+	"github.com/samber/lo"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/openmeterio/openmeter/pkg/datetime"
+)
+
+func TestEntitlementTemplate_JSON(t *testing.T) {
+	tests := []struct {
+		Name                string
+		EntitlementTemplate *EntitlementTemplate
+		ExpectedError       bool
+	}{
+		{
+			Name: "Metered",
+			EntitlementTemplate: NewEntitlementTemplateFrom(MeteredEntitlementTemplate{
+				Metadata: map[string]string{
+					"key": "value",
+				},
+				IsSoftLimit:             true,
+				IssueAfterReset:         lo.ToPtr(500.0),
+				IssueAfterResetPriority: lo.ToPtr[uint8](1),
+				PreserveOverageAtReset:  lo.ToPtr(true),
+				UsagePeriod:             datetime.MustParseDuration(t, "P1M"),
+			}),
+		},
+		{
+			Name: "Static",
+			EntitlementTemplate: NewEntitlementTemplateFrom(StaticEntitlementTemplate{
+				Metadata: map[string]string{
+					"key": "value",
+				},
+				Config: []byte(`{"key":"value"}`),
+			}),
+		},
+		{
+			Name: "Boolean",
+			EntitlementTemplate: NewEntitlementTemplateFrom(BooleanEntitlementTemplate{
+				Metadata: map[string]string{
+					"key": "value",
+				},
+			}),
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.Name, func(t *testing.T) {
+			b, err := json.Marshal(&test.EntitlementTemplate)
+			require.NoError(t, err)
+
+			t.Logf("Serialized EntitlementTemplate: %s", string(b))
+
+			d := &EntitlementTemplate{}
+			err = json.Unmarshal(b, d)
+			require.NoError(t, err)
+
+			assert.Equal(t, test.EntitlementTemplate, d)
+		})
+	}
+}
+
+func TestEntitlementTemplateEqual(t *testing.T) {
+	tests := []struct {
+		Name string
+
+		Left  *EntitlementTemplate
+		Right *EntitlementTemplate
+
+		ExpectedResult bool
+	}{
+		{
+			Name: "Equal",
+			Left: NewEntitlementTemplateFrom(
+				MeteredEntitlementTemplate{
+					Metadata:                map[string]string{"name": "metered"},
+					IsSoftLimit:             true,
+					IssueAfterReset:         lo.ToPtr(1000.0),
+					IssueAfterResetPriority: lo.ToPtr[uint8](5),
+					PreserveOverageAtReset:  lo.ToPtr(true),
+					UsagePeriod:             datetime.MustParseDuration(t, "P1M"),
+				},
+			),
+			Right: NewEntitlementTemplateFrom(
+				MeteredEntitlementTemplate{
+					Metadata:                map[string]string{"name": "metered"},
+					IsSoftLimit:             true,
+					IssueAfterReset:         lo.ToPtr(1000.0),
+					IssueAfterResetPriority: lo.ToPtr[uint8](5),
+					PreserveOverageAtReset:  lo.ToPtr(true),
+					UsagePeriod:             datetime.MustParseDuration(t, "P1M"),
+				},
+			),
+			ExpectedResult: true,
+		},
+		{
+			Name: "ContentMismatch",
+			Left: NewEntitlementTemplateFrom(
+				MeteredEntitlementTemplate{
+					Metadata:                map[string]string{"name": "metered1"},
+					IsSoftLimit:             true,
+					IssueAfterReset:         lo.ToPtr(1000.0),
+					IssueAfterResetPriority: lo.ToPtr[uint8](5),
+					PreserveOverageAtReset:  lo.ToPtr(true),
+					UsagePeriod:             datetime.MustParseDuration(t, "P1M"),
+				},
+			),
+			Right: NewEntitlementTemplateFrom(
+				MeteredEntitlementTemplate{
+					Metadata:                map[string]string{"name": "metered2"},
+					IsSoftLimit:             false,
+					IssueAfterReset:         lo.ToPtr(2000.0),
+					IssueAfterResetPriority: lo.ToPtr[uint8](1),
+					PreserveOverageAtReset:  lo.ToPtr(false),
+					UsagePeriod:             datetime.MustParseDuration(t, "P3M"),
+				},
+			),
+			ExpectedResult: false,
+		},
+		{
+			Name: "TypeMismatch",
+			Left: NewEntitlementTemplateFrom(
+				MeteredEntitlementTemplate{
+					Metadata:                map[string]string{"name": "metered1"},
+					IsSoftLimit:             true,
+					IssueAfterReset:         lo.ToPtr(1000.0),
+					IssueAfterResetPriority: lo.ToPtr[uint8](5),
+					PreserveOverageAtReset:  lo.ToPtr(true),
+					UsagePeriod:             datetime.MustParseDuration(t, "P1M"),
+				},
+			),
+			Right: NewEntitlementTemplateFrom(
+				StaticEntitlementTemplate{
+					Metadata: map[string]string{"name": "metered2"},
+					Config:   []byte(`"name": "metered1"`),
+				},
+			),
+			ExpectedResult: false,
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.Name, func(t *testing.T) {
+			match := test.Left.Equal(test.Right)
+			assert.Equal(t, test.ExpectedResult, match)
+		})
+	}
+}

openmeter/productcatalog/errors.go

@@ -0,0 +1,667 @@
+package productcatalog
+
+import (
+	"fmt"
+	"net/http"
+	"strings"
+
+	"github.com/samber/lo"
+
+	"github.com/openmeterio/openmeter/pkg/datetime"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+// PlanAddon errors
+
+const ErrCodePlanAddonIncompatibleStatus models.ErrorCode = "plan_addon_incompatible_status"
+
+var ErrPlanAddonIncompatibleStatus = models.NewValidationIssue(
+	ErrCodePlanAddonIncompatibleStatus,
+	"plan status is incompatible with the addon status",
+	models.WithFieldString("status"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodePlanAddonMaxQuantityMustBeSet models.ErrorCode = "plan_addon_max_quantity_must_be_set"
+
+var ErrPlanAddonMaxQuantityMustBeSet = models.NewValidationIssue(
+	ErrCodePlanAddonMaxQuantityMustBeSet,
+	"maximum quantity, when set, must be a positive integer for add-ons with multiple instance type",
+	models.WithFieldString("maxQuantity"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodePlanAddonMaxQuantityMustNotBeSet models.ErrorCode = "plan_addon_max_quantity_must_not_be_set"
+
+var ErrPlanAddonMaxQuantityMustNotBeSet = models.NewValidationIssue(
+	ErrCodePlanAddonMaxQuantityMustNotBeSet,
+	"maximum quantity must not be set for add-on with single instance type",
+	models.WithFieldString("maxQuantity"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodePlanAddonCurrencyMismatch models.ErrorCode = "plan_addon_currency_mismatch"
+
+var ErrPlanAddonCurrencyMismatch = models.NewValidationIssue(
+	ErrCodePlanAddonCurrencyMismatch,
+	"currency of the plan and addon must match",
+	models.WithFieldString("currency"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodePlanAddonUnknownPlanPhaseKey models.ErrorCode = "plan_addon_unknown_plan_phase_key"
+
+var ErrPlanAddonUnknownPlanPhaseKey = models.NewValidationIssue(
+	ErrCodePlanAddonUnknownPlanPhaseKey,
+	"add-on must define valid/existing plan phase key from which the add-on is available for purchase",
+	models.WithFieldString("fromPlanPhase"),
+	models.WithWarningSeverity(),
+)
+
+// RateCard errors
+
+const ErrCodeRateCardKeyMismatch models.ErrorCode = "rate_card_key_mismatch"
+
+var ErrRateCardKeyMismatch = models.NewValidationIssue(
+	ErrCodeRateCardKeyMismatch,
+	"key must match",
+	models.WithFieldString("key"),
+	models.WithWarningSeverity(),
+)
+
+const ErrCodeRateCardPriceTypeMismatch models.ErrorCode = "rate_card_price_type_mismatch"
+
+var ErrRateCardPriceTypeMismatch = models.NewValidationIssue(
+	ErrCodeRateCardPriceTypeMismatch,
+	"price type must match",
+	models.WithFieldString("price"),
+	models.WithWarningSeverity(),
+)
+
+const ErrCodeRateCardPricePaymentTermMismatch models.ErrorCode = "rate_card_price_payment_term_mismatch"
+
+var ErrRateCardPricePaymentTermMismatch = models.NewValidationIssue(
+	ErrCodeRateCardPricePaymentTermMismatch,
+	"price payment term must match",
+	models.WithFieldString("price"),
+	models.WithWarningSeverity(),
+)
+
+const ErrCodeRateCardOnlyFlatPriceAllowed models.ErrorCode = "rate_card_only_flat_price_allowed"
+
+var ErrRateCardOnlyFlatPriceAllowed = models.NewValidationIssue(
+	ErrCodeRateCardOnlyFlatPriceAllowed,
+	"only flat price is allowed",
+	models.WithFieldString("price"),
+	models.WithWarningSeverity(),
+)
+
+const ErrCodeRateCardFeatureNotFound models.ErrorCode = "rate_card_feature_not_found"
+
+var ErrRateCardFeatureNotFound = models.NewValidationIssue(
+	ErrCodeRateCardFeatureNotFound,
+	"feature not found",
+	models.WithFieldString("featureKey"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeRateCardFeatureArchived models.ErrorCode = "rate_card_feature_archived"
+
+var ErrRateCardFeatureArchived = models.NewValidationIssue(
+	ErrCodeRateCardFeatureArchived,
+	"feature archived",
+	models.WithFieldString("featureKey"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeRateCardFeatureMismatch models.ErrorCode = "rate_card_feature_mismatch"
+
+var ErrRateCardFeatureMismatch = models.NewValidationIssue(
+	ErrCodeRateCardFeatureMismatch,
+	"feature id and key must reference the same feature",
+	models.WithFieldString("featureKey"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeRateCardFeatureIDMismatch models.ErrorCode = "rate_card_feature_id_mismatch"
+
+var ErrRateCardFeatureIDMismatch = models.NewValidationIssue(
+	ErrCodeRateCardFeatureIDMismatch,
+	"feature identifiers id must match",
+	models.WithFieldString("featureId"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeRateCardFeatureKeyMismatch models.ErrorCode = "rate_card_feature_key_mismatch"
+
+var ErrRateCardFeatureKeyMismatch = models.NewValidationIssue(
+	ErrCodeRateCardFeatureKeyMismatch,
+	"feature key must match",
+	models.WithFieldString("featureKey"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeRateCardBillingCadenceMismatch models.ErrorCode = "rate_card_billing_cadence_mismatch"
+
+var ErrRateCardBillingCadenceMismatch = models.NewValidationIssue(
+	ErrCodeRateCardBillingCadenceMismatch,
+	"billing cadence must match",
+	models.WithFieldString("billingCadence"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeAddonRateCardUnitConfigMismatch models.ErrorCode = "addon_rate_card_unit_config_mismatch"
+
+// ErrAddonRateCardUnitConfigMismatch is raised when an addon rate card carries a unit_config that differs
+// from the rate card it extends. Addons layer price/entitlement/discounts additively but do not
+// redefine the unit conversion; a divergent unit_config would be silently dropped by the overlay, so
+// it is rejected here rather than accepted and ignored.
+var ErrAddonRateCardUnitConfigMismatch = models.NewValidationIssue(
+	ErrCodeAddonRateCardUnitConfigMismatch,
+	"unit config must match",
+	models.WithFieldString("unitConfig"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeRateCardEntitlementTemplateTypeMismatch models.ErrorCode = "rate_card_entitlement_template_type_mismatch"
+
+var ErrRateCardEntitlementTemplateTypeMismatch = models.NewValidationIssue(
+	ErrCodeRateCardEntitlementTemplateTypeMismatch,
+	"entitlement template type must match",
+	models.WithFieldString("type"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeRateCardStaticEntitlementTemplateNotAllowed models.ErrorCode = "rate_card_static_entitlement_template_not_allowed"
+
+var ErrRateCardStaticEntitlementTemplateNotAllowed = models.NewValidationIssue(
+	ErrCodeRateCardStaticEntitlementTemplateNotAllowed,
+	"static entitlement template is not allowed",
+	models.WithFieldString("type"),
+	models.WithWarningSeverity(),
+)
+
+const ErrCodeRateCardMeteredEntitlementTemplateUsagePeriodMismatch models.ErrorCode = "rate_card_metered_entitlement_template_usage_period_mismatch"
+
+var ErrRateCardMeteredEntitlementTemplateUsagePeriodMismatch = models.NewValidationIssue(
+	ErrCodeRateCardMeteredEntitlementTemplateUsagePeriodMismatch,
+	"usage period for metered entitlement template must match",
+	models.WithFieldString("usagePeriod"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeRateCardPercentageDiscountNotAllowed models.ErrorCode = "rate_card_percentage_discount_not_allowed"
+
+var ErrRateCardPercentageDiscountNotAllowed = models.NewValidationIssue(
+	ErrCodeRateCardPercentageDiscountNotAllowed,
+	"percentage discount is not allowed",
+	models.WithFieldString("percentage"),
+	models.WithWarningSeverity(),
+)
+
+const ErrCodeRateCardDuplicatedKey models.ErrorCode = "rate_card_duplicated_key"
+
+var ErrRateCardDuplicatedKey = models.NewValidationIssue(
+	ErrCodeRateCardDuplicatedKey,
+	"duplicated key",
+	models.WithFieldString("key"),
+	models.WithCriticalSeverity(),
+)
+
+const ErrCodeRateCardEntitlementTemplateWithNoFeature models.ErrorCode = "entitlement_template_with_no_feature"
+
+var ErrRateCardEntitlementTemplateWithNoFeature = models.NewValidationIssue(
+	ErrCodeRateCardEntitlementTemplateWithNoFeature,
+	"entitlement template requires feature to be associated with",
+	models.WithFieldString("featureKey"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeEffectivePeriodFromAfterTo models.ErrorCode = "effective_period_from_after_to"
+
+var ErrEffectivePeriodFromAfterTo = models.NewValidationIssue(
+	ErrCodeEffectivePeriodFromAfterTo,
+	"effectiveFrom is after effectiveTo",
+	models.WithFieldString("effectiveFrom"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeEffectivePeriodFromNotSet models.ErrorCode = "effective_period_from_not_set"
+
+var ErrEffectivePeriodFromNotSet = models.NewValidationIssue(
+	ErrCodeEffectivePeriodFromNotSet,
+	"effectiveFrom is must be provided if effectiveTo is set",
+	models.WithFieldString("effectiveFrom"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeCurrencyInvalid models.ErrorCode = "currency_invalid"
+
+var ErrCurrencyInvalid = models.NewValidationIssue(
+	ErrCodeCurrencyInvalid,
+	"currency is invalid",
+	models.WithFieldString("currency"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeEntitlementTemplateInvalidIssueAfterResetWithPriority models.ErrorCode = "entitlement_template_invalid_issue_after_reset_with_priority"
+
+var ErrEntitlementTemplateInvalidIssueAfterResetWithPriority = models.NewValidationIssue(
+	ErrCodeEntitlementTemplateInvalidIssueAfterResetWithPriority,
+	"invalid entitlement template as issue after reset is required if issue after reset priority is set",
+	models.WithFieldString("issueAfterReset"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeEntitlementTemplateIssueAfterResetRequired models.ErrorCode = "entitlement_template_issue_after_reset_required"
+
+var ErrEntitlementTemplateIssueAfterResetRequired = models.NewValidationIssue(
+	ErrCodeEntitlementTemplateIssueAfterResetRequired,
+	"issueAfterReset is required for metered entitlement templates",
+	models.WithFieldString("entitlementTemplate", "issueAfterReset"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeEntitlementTemplateNegativeUsagePeriod models.ErrorCode = "entitlement_template_negative_usage_period"
+
+var ErrEntitlementTemplateNegativeUsagePeriod = models.NewValidationIssue(
+	ErrCodeEntitlementTemplateNegativeUsagePeriod,
+	"usage period must be positive",
+	models.WithFieldString("usagePeriod"),
+	models.WithWarningSeverity(),
+)
+
+const ErrCodeEntitlementTemplateUsagePeriodLessThenAnHour models.ErrorCode = "entitlement_template_usage_period_less_then_an_hour"
+
+var ErrEntitlementTemplateUsagePeriodLessThenAnHour = models.NewValidationIssue(
+	ErrCodeEntitlementTemplateUsagePeriodLessThenAnHour,
+	"usage period must be at least 1 hour",
+	models.WithFieldString("usagePeriod"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeEntitlementTemplateInvalidJSONConfig models.ErrorCode = "entitlement_template_invalid_json_config"
+
+var ErrEntitlementTemplateInvalidJSONConfig = models.NewValidationIssue(
+	ErrCodeEntitlementTemplateInvalidJSONConfig,
+	"invalid JSON in static entitlement config",
+	models.WithFieldString("entitlementTemplate", "config"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeRateCardKeyFeatureKeyMismatch models.ErrorCode = "rate_card_key_feature_key_mismatch"
+
+var ErrRateCardKeyFeatureKeyMismatch = models.NewValidationIssue(
+	ErrCodeRateCardKeyFeatureKeyMismatch,
+	"rate card key must match feature key",
+	models.WithFieldString("key"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodePercentageDiscountInvalidValue models.ErrorCode = "percentage_discount_invalid_value"
+
+var ErrPercentageDiscountInvalidValue = models.NewValidationIssue(
+	ErrCodePercentageDiscountInvalidValue,
+	"percentage must be between 0 and 100",
+	models.WithFieldString("percentage"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeUsageDiscountNegativeQuantity models.ErrorCode = "usage_discount_negative_quantity"
+
+var ErrUsageDiscountNegativeQuantity = models.NewValidationIssue(
+	ErrCodeUsageDiscountNegativeQuantity,
+	"usage must be greater than 0",
+	models.WithFieldString("quantity"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeUsageDiscountWithFlatPrice models.ErrorCode = "usage_discount_with_flat_price"
+
+var ErrUsageDiscountWithFlatPrice = models.NewValidationIssue(
+	ErrCodeUsageDiscountWithFlatPrice,
+	"usage discount is not supported for flat price",
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeBillingCadenceInvalidValue models.ErrorCode = "billing_cadence_invalid_value"
+
+var ErrBillingCadenceInvalidValue = models.NewValidationIssue(
+	ErrCodeBillingCadenceInvalidValue,
+	"billing cadence must be positive and 1 hour long duration at least",
+	models.WithFieldString("billingCadence"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeRateCardMultipleBillingCadence models.ErrorCode = "rate_card_multiple_billing_cadence"
+
+var ErrRateCardMultipleBillingCadence = models.NewValidationIssue(
+	ErrCodeRateCardMultipleBillingCadence,
+	"ratecards with prices must have the exact same billing cadence",
+	models.WithFieldString("billingCadence"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeRateCardBillingCadenceUnaligned models.ErrorCode = "rate_card_billing_cadence_unaligned"
+
+var ErrRateCardBillingCadenceUnaligned = models.NewValidationIssue(
+	ErrCodeRateCardBillingCadenceUnaligned,
+	"ratecards with prices must have compatible billing cadence",
+	models.WithFieldString("billingCadence"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeRateCardUsageBasedPriceWithNoFeature models.ErrorCode = "usage_based_price_with_no_feature"
+
+var ErrRateCardUsageBasedPriceWithNoFeature = models.NewValidationIssue(
+	ErrCodeRateCardUsageBasedPriceWithNoFeature,
+	"usage-based price requires feature to be associated with",
+	models.WithFieldString("featureKey"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeRateCardUnitConfigRequiresUsageBasedPrice models.ErrorCode = "unit_config_requires_usage_based_price"
+
+var ErrRateCardUnitConfigRequiresUsageBasedPrice = models.NewValidationIssue(
+	ErrCodeRateCardUnitConfigRequiresUsageBasedPrice,
+	"unit config requires a usage-based price (unit, graduated, or volume)",
+	models.WithFieldString("unit_config"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeUnitConfigNotRepresentable models.ErrorCode = "unit_config_not_representable"
+
+var ErrUnitConfigNotRepresentable = models.NewValidationIssue(
+	ErrCodeUnitConfigNotRepresentable,
+	"this resource uses unit_config and is only available via the v3 API",
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeRateCardUsageBasedPriceWithFeatureAndNoMeter models.ErrorCode = "usage_based_price_with_feature_and_no_meter"
+
+var ErrRateCardUsageBasedPriceWithFeatureAndNoMeter = models.NewValidationIssue(
+	ErrCodeRateCardUsageBasedPriceWithFeatureAndNoMeter,
+	"usage-based price requires feature with meter to be associated with",
+	models.WithFieldString("featureKey"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+// Addon errors
+
+const ErrCodeAddonKeyEmpty models.ErrorCode = "addon_key_empty"
+
+var ErrAddonKeyEmpty = models.NewValidationIssue(
+	ErrCodeAddonKeyEmpty,
+	"key must not be empty",
+	models.WithFieldString("key"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeAddonNameEmpty models.ErrorCode = "addon_name_empty"
+
+var ErrAddonNameEmpty = models.NewValidationIssue(
+	ErrCodeAddonNameEmpty,
+	"name must not be empty",
+	models.WithFieldString("name"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeAddonInvalidInstanceType models.ErrorCode = "addon_invalid_instance_type"
+
+var ErrAddonInvalidInstanceType = models.NewValidationIssue(
+	ErrCodeAddonInvalidInstanceType,
+	"invalid instance type",
+	models.WithFieldString("instanceType"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeAddonInvalidStatus models.ErrorCode = "addon_invalid_status"
+
+var ErrAddonInvalidStatus = models.NewValidationIssue(
+	ErrCodeAddonInvalidStatus,
+	"invalid status",
+	models.WithFieldString("status"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeAddonInvalidStatusForPublish models.ErrorCode = "addon_invalid_status_for_publish"
+
+var ErrAddonInvalidStatusForPublish = models.NewValidationIssue(
+	ErrCodeAddonInvalidStatusForPublish,
+	"only draft add-ons can be published",
+	models.WithFieldString("status"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeAddonInvalidPriceForMultiInstance models.ErrorCode = "addon_invalid_ratecard_price_for_multi_instance"
+
+var ErrAddonInvalidPriceForMultiInstance = models.NewValidationIssue(
+	ErrCodeAddonInvalidPriceForMultiInstance,
+	"only free or flat price ratecards are allowed for add-on with multiple instance type",
+	models.WithFieldString("price"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeAddonHasNoRateCards models.ErrorCode = "addon_has_no_rate_cards"
+
+var ErrAddonHasNoRateCards = models.NewValidationIssue(
+	ErrCodeAddonHasNoRateCards,
+	"add-on must have at least one rate card",
+	models.WithFieldString("rateCards"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+// Generic errors
+
+const ErrCodeResourceKeyEmpty models.ErrorCode = "resource_key_empty"
+
+var ErrResourceKeyEmpty = models.NewValidationIssue(
+	ErrCodeResourceKeyEmpty,
+	"key must not be empty",
+	models.WithFieldString("key"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeResourceNameEmpty models.ErrorCode = "resource_name_empty"
+
+var ErrResourceNameEmpty = models.NewValidationIssue(
+	ErrCodeResourceNameEmpty,
+	"name must not be empty",
+	models.WithFieldString("name"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeNamespaceEmpty models.ErrorCode = "resource_namespace_empty"
+
+var ErrNamespaceEmpty = models.NewValidationIssue(
+	ErrCodeNamespaceEmpty,
+	"namespace must not be empty",
+	models.WithFieldString("namespace"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodeIDEmpty models.ErrorCode = "resource_id_empty"
+
+var ErrIDEmpty = models.NewValidationIssue(
+	ErrCodeIDEmpty,
+	"id must not be empty",
+	models.WithFieldString("id"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+// Alignment errors
+
+const ErrCodeDeprecatedUnalignedSubscription models.ErrorCode = "deprecated_unaligned_subscription"
+
+var ErrDeprecatedUnalignedSubscription = models.NewValidationIssue(
+	ErrCodeDeprecatedUnalignedSubscription,
+	"unaligned subscriptions are being deprecated",
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+// Plan errors
+
+var ErrPlanBillingCadenceAllowedValues = []datetime.ISODurationString{
+	"P1W",
+	"P2W",
+	"P4W",
+	"P1M",
+	"P3M",
+	"P6M",
+	"P12M",
+	"P1Y",
+}
+
+const ErrCodePlanBillingCadenceInvalid models.ErrorCode = "plan_billing_cadence_invalid"
+
+var ErrPlanBillingCadenceInvalid = models.NewValidationIssue(
+	ErrCodePlanBillingCadenceInvalid,
+	fmt.Sprintf("billing cadence must be one of the following: %s", strings.Join(lo.Map(ErrPlanBillingCadenceAllowedValues, func(v datetime.ISODurationString, _ int) string { return v.String() }), ", ")),
+	models.WithFieldString("billingCadence"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodePlanPhaseWithNegativeDuration models.ErrorCode = "plan_phase_with_negative_duration"
+
+var ErrPlanPhaseWithNegativeDuration = models.NewValidationIssue(
+	ErrCodePlanPhaseWithNegativeDuration,
+	"duration must be positive",
+	models.WithFieldString("duration"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodePlanPhaseDurationLessThenAnHour models.ErrorCode = "plan_phase_duration_less_then_an_hour"
+
+var ErrPlanPhaseDurationLessThenAnHour = models.NewValidationIssue(
+	ErrCodePlanPhaseDurationLessThenAnHour,
+	"duration must be at least 1 hour",
+	models.WithFieldString("duration"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodePlanPhaseDuplicatedKey models.ErrorCode = "plan_phase_duplicated_key"
+
+var ErrPlanPhaseDuplicatedKey = models.NewValidationIssue(
+	ErrCodePlanPhaseDuplicatedKey,
+	"duplicated key",
+	models.WithFieldString("key"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodePlanInvalidStatus models.ErrorCode = "plan_invalid_status"
+
+var ErrPlanInvalidStatus = models.NewValidationIssue(
+	ErrCodePlanInvalidStatus,
+	"invalid status",
+	models.WithFieldString("status"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodePlanWithNoPhases models.ErrorCode = "plan_with_no_phases"
+
+var ErrPlanWithNoPhases = models.NewValidationIssue(
+	ErrCodePlanWithNoPhases,
+	"plan must have at least one phase",
+	models.WithFieldString("phases"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodePlanHasNonLastPhaseWithNoDuration models.ErrorCode = "plan_has_non_last_phase_with_no_duration"
+
+var ErrPlanHasNonLastPhaseWithNoDuration = models.NewValidationIssue(
+	ErrCodePlanHasNonLastPhaseWithNoDuration,
+	"duration must be set for plan phase if it is not the last one",
+	models.WithFieldString("duration"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodePlanHasLastPhaseWithDuration models.ErrorCode = "plan_has_last_phase_with_duration"
+
+var ErrPlanHasLastPhaseWithDuration = models.NewValidationIssue(
+	ErrCodePlanHasLastPhaseWithDuration,
+	"duration must not be set for the last plan phase",
+	models.WithFieldString("duration"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodePlanPhaseHasNoRateCards models.ErrorCode = "plan_phase_has_no_rate_cards"
+
+var ErrPlanPhaseHasNoRateCards = models.NewValidationIssue(
+	ErrCodePlanPhaseHasNoRateCards,
+	"plan phase must have at least one rate card",
+	models.WithFieldString("rateCards"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodePlanHasIncompatibleAddon models.ErrorCode = "plan_has_incompatible_addon"
+
+var ErrPlanHasIncompatibleAddon = models.NewValidationIssue(
+	ErrCodePlanHasIncompatibleAddon,
+	"plan has incompatible add-on assignment",
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+const ErrCodePlanBillingCadenceNotCompatible models.ErrorCode = "plan_billing_cadence_not_compatible"
+
+var ErrPlanBillingCadenceNotCompatible = models.NewValidationIssue(
+	ErrCodePlanBillingCadenceNotCompatible,
+	"plan billing cadence is not compatible with rate card billing cadence",
+	models.WithFieldString("billingCadence"),
+	models.WithWarningSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)

openmeter/productcatalog/feature/connector.go

@@ -0,0 +1,382 @@
+package feature
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"slices"
+
+	"github.com/oapi-codegen/nullable"
+	"github.com/oklog/ulid/v2"
+	"github.com/samber/lo"
+
+	meterpkg "github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/openmeter/watermill/eventbus"
+	"github.com/openmeterio/openmeter/pkg/clock"
+	"github.com/openmeterio/openmeter/pkg/filter"
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+	"github.com/openmeterio/openmeter/pkg/ref"
+	"github.com/openmeterio/openmeter/pkg/sortx"
+)
+
+type CreateFeatureInputs struct {
+	Name                string              `json:"name"`
+	Description         *string             `json:"description,omitempty"`
+	Key                 string              `json:"key"`
+	Namespace           string              `json:"namespace"`
+	MeterID             *string             `json:"meterID"`
+	MeterGroupByFilters MeterGroupByFilters `json:"meterGroupByFilters"`
+	UnitCost            *UnitCost           `json:"unitCost"`
+	Metadata            map[string]string   `json:"metadata"`
+}
+
+type UpdateFeatureInputs struct {
+	Namespace string                      `json:"namespace"`
+	ID        string                      `json:"id"`
+	UnitCost  nullable.Nullable[UnitCost] `json:"unitCost"`
+}
+
+func (i UpdateFeatureInputs) Validate() error {
+	var errs []error
+
+	if i.Namespace == "" {
+		errs = append(errs, errors.New("namespace is required"))
+	}
+
+	if i.ID == "" {
+		errs = append(errs, errors.New("id is required"))
+	}
+
+	if !i.UnitCost.IsSpecified() {
+		errs = append(errs, errors.New("unitCost is required"))
+	}
+
+	return models.NewNillableGenericValidationError(errors.Join(errs...))
+}
+
+// TODO: refactor to service pattern
+type FeatureConnector interface {
+	// Feature Management
+	CreateFeature(ctx context.Context, feature CreateFeatureInputs) (Feature, error)
+	UpdateFeature(ctx context.Context, input UpdateFeatureInputs) (Feature, error)
+	// Should just use deletedAt, there's no real "archiving"
+	ArchiveFeature(ctx context.Context, featureID models.NamespacedID) error
+	ListFeatures(ctx context.Context, params ListFeaturesParams) (pagination.Result[Feature], error)
+	GetFeature(ctx context.Context, namespace string, idOrKey string, includeArchived IncludeArchivedFeature) (*Feature, error)
+
+	// ResolveFeatureMeters resolves the feature meters for a given namespace and feature refs.
+	// Keys always resolve to the latest available feature for that key.
+	// Explicit IDs are returned in the ID index, and also in the key index when they are the latest feature for that key.
+	ResolveFeatureMeters(ctx context.Context, namespace string, featureRefs ...ref.IDOrKey) (FeatureMeters, error)
+}
+
+type IncludeArchivedFeature bool
+
+const (
+	IncludeArchivedFeatureTrue  IncludeArchivedFeature = true
+	IncludeArchivedFeatureFalse IncludeArchivedFeature = false
+)
+
+// FeatureOrderBy is the order by clause for features
+type FeatureOrderBy string
+
+const (
+	FeatureOrderByKey       FeatureOrderBy = "key"
+	FeatureOrderByName      FeatureOrderBy = "name"
+	FeatureOrderByCreatedAt FeatureOrderBy = "created_at"
+	FeatureOrderByUpdatedAt FeatureOrderBy = "updated_at"
+)
+
+func (f FeatureOrderBy) Values() []FeatureOrderBy {
+	return []FeatureOrderBy{
+		FeatureOrderByKey,
+		FeatureOrderByName,
+		FeatureOrderByCreatedAt,
+		FeatureOrderByUpdatedAt,
+	}
+}
+
+func (f FeatureOrderBy) Validate() error {
+	if !slices.Contains(f.Values(), f) {
+		return models.NewGenericValidationError(fmt.Errorf("invalid feature order by: %s", f))
+	}
+
+	return nil
+}
+
+type ListFeaturesParams struct {
+	IDsOrKeys       []string
+	Key             *filter.FilterString
+	Name            *filter.FilterString
+	Namespace       string
+	MeterIDs        *filter.FilterULID
+	MeterSlugs      []string // Kept for ingest pipeline compat (queries via ent edge on meter key)
+	IncludeArchived bool
+	Page            pagination.Page
+	OrderBy         FeatureOrderBy
+	Order           sortx.Order
+	// will be deprecated
+	Limit int
+	// will be deprecated
+	Offset int
+}
+
+func (p ListFeaturesParams) Validate() error {
+	var errs []error
+
+	if p.Namespace == "" {
+		errs = append(errs, errors.New("namespace is required"))
+	}
+	if p.MeterIDs != nil {
+		if err := p.MeterIDs.Validate(); err != nil {
+			errs = append(errs, err)
+		}
+	}
+	if !p.Page.IsZero() {
+		if err := p.Page.Validate(); err != nil {
+			errs = append(errs, err)
+		}
+	}
+	if p.Key != nil {
+		if err := p.Key.Validate(); err != nil {
+			errs = append(errs, err)
+		}
+	}
+	if p.Name != nil {
+		if err := p.Name.Validate(); err != nil {
+			errs = append(errs, err)
+		}
+	}
+	if p.OrderBy != "" {
+		if err := p.OrderBy.Validate(); err != nil {
+			errs = append(errs, err)
+		}
+	}
+
+	return models.NewNillableGenericValidationError(errors.Join(errs...))
+}
+
+type featureConnector struct {
+	featureRepo  FeatureRepo
+	meterService meterpkg.Service
+	publisher    eventbus.Publisher
+
+	validMeterAggregations []meterpkg.MeterAggregation
+}
+
+func NewFeatureConnector(
+	featureRepo FeatureRepo,
+	meterService meterpkg.Service,
+	publisher eventbus.Publisher,
+) FeatureConnector {
+	return &featureConnector{
+		featureRepo:  featureRepo,
+		meterService: meterService,
+		publisher:    publisher,
+
+		validMeterAggregations: []meterpkg.MeterAggregation{
+			meterpkg.MeterAggregationSum,
+			meterpkg.MeterAggregationCount,
+			meterpkg.MeterAggregationUniqueCount,
+			meterpkg.MeterAggregationLatest,
+		},
+	}
+}
+
+// CreateFeature creates a new feature
+func (c *featureConnector) CreateFeature(ctx context.Context, feature CreateFeatureInputs) (Feature, error) {
+	// Validate meter configuration
+	var resolvedMeter *meterpkg.Meter
+
+	if feature.MeterID != nil {
+		meterID := *feature.MeterID
+
+		// nosemgrep: trailofbits.go.invalid-usage-of-modified-variable.invalid-usage-of-modified-variable
+		meter, err := c.meterService.GetMeterByIDOrSlug(ctx, meterpkg.GetMeterInput{
+			Namespace: feature.Namespace,
+			IDOrSlug:  meterID,
+		})
+		if err != nil {
+			if meterpkg.IsMeterNotFoundError(err) {
+				return Feature{}, meterpkg.NewMeterNotFoundError(meterID)
+			}
+			return Feature{}, fmt.Errorf("get meter %s: %w", meterID, err)
+		}
+
+		// Normalize to meter ID
+		feature.MeterID = &meter.ID
+
+		resolvedMeter = &meter
+
+		if !slices.Contains(c.validMeterAggregations, meter.Aggregation) {
+			return Feature{}, &FeatureInvalidMeterAggregationError{Aggregation: meter.Aggregation, MeterSlug: meter.Key, ValidAggregations: c.validMeterAggregations}
+		}
+
+		if feature.MeterGroupByFilters != nil {
+			if err = feature.MeterGroupByFilters.Validate(meter); err != nil {
+				return Feature{}, err
+			}
+		}
+	}
+
+	// Validate unit cost
+	if feature.UnitCost != nil {
+		if err := feature.UnitCost.Validate(); err != nil {
+			return Feature{}, models.NewGenericValidationError(err)
+		}
+
+		if feature.UnitCost.Type == UnitCostTypeLLM {
+			if resolvedMeter == nil {
+				return Feature{}, models.NewGenericValidationError(
+					fmt.Errorf("LLM unit cost requires a meter to be associated with the feature"),
+				)
+			}
+
+			if err := feature.UnitCost.ValidateWithMeter(*resolvedMeter); err != nil {
+				return Feature{}, models.NewGenericValidationError(err)
+			}
+		}
+	}
+
+	// Validate feature key
+	if _, err := ulid.Parse(feature.Key); err == nil {
+		return Feature{}, models.NewGenericValidationError(fmt.Errorf("Feature key cannot be a valid ULID"))
+	}
+
+	// Check key is not taken
+	found, err := c.featureRepo.GetByIdOrKey(ctx, feature.Namespace, feature.Key, false)
+	if err != nil {
+		if _, ok := err.(*FeatureNotFoundError); !ok {
+			return Feature{}, err
+		}
+	} else {
+		return Feature{}, &FeatureWithNameAlreadyExistsError{Name: feature.Key, ID: found.ID}
+	}
+
+	// Create the feature
+	createdFeature, err := c.featureRepo.CreateFeature(ctx, feature)
+	if err != nil {
+		return Feature{}, err
+	}
+
+	// Populate MeterSlug from resolved meter for v1 API backward compat
+	if resolvedMeter != nil {
+		createdFeature.MeterSlug = &resolvedMeter.Key
+	}
+
+	// Publish the feature created event
+	featureCreatedEvent := NewFeatureCreateEvent(ctx, &createdFeature)
+	if err := c.publisher.Publish(ctx, featureCreatedEvent); err != nil {
+		return createdFeature, fmt.Errorf("failed to publish feature created event: %w", err)
+	}
+
+	return createdFeature, nil
+}
+
+// UpdateFeature updates a feature's unit cost
+func (c *featureConnector) UpdateFeature(ctx context.Context, input UpdateFeatureInputs) (Feature, error) {
+	if err := input.Validate(); err != nil {
+		return Feature{}, err
+	}
+
+	// Get the feature (rejects archived/not found)
+	feat, err := c.GetFeature(ctx, input.Namespace, input.ID, IncludeArchivedFeatureFalse)
+	if err != nil {
+		return Feature{}, err
+	}
+
+	// Validate unit cost if a value is provided (not null/clear)
+	if !input.UnitCost.IsNull() {
+		unitCost, err := input.UnitCost.Get()
+		if err != nil {
+			return Feature{}, models.NewGenericValidationError(err)
+		}
+
+		if err := unitCost.Validate(); err != nil {
+			return Feature{}, models.NewGenericValidationError(err)
+		}
+
+		if unitCost.Type == UnitCostTypeLLM {
+			if feat.MeterSlug == nil {
+				return Feature{}, models.NewGenericValidationError(
+					fmt.Errorf("LLM unit cost requires a meter to be associated with the feature"),
+				)
+			}
+
+			meter, err := c.meterService.GetMeterByIDOrSlug(ctx, meterpkg.GetMeterInput{
+				Namespace: input.Namespace,
+				IDOrSlug:  *feat.MeterSlug,
+			})
+			if err != nil {
+				return Feature{}, err
+			}
+
+			if err := unitCost.ValidateWithMeter(meter); err != nil {
+				return Feature{}, models.NewGenericValidationError(err)
+			}
+		}
+	}
+
+	updatedFeature, err := c.featureRepo.UpdateFeature(ctx, input)
+	if err != nil {
+		return Feature{}, err
+	}
+
+	// Publish the feature updated event
+	featureUpdatedEvent := NewFeatureUpdateEvent(ctx, &updatedFeature)
+	if err := c.publisher.Publish(ctx, featureUpdatedEvent); err != nil {
+		return updatedFeature, fmt.Errorf("failed to publish feature updated event: %w", err)
+	}
+
+	return updatedFeature, nil
+}
+
+// ArchiveFeature archives a feature
+func (c *featureConnector) ArchiveFeature(ctx context.Context, featureID models.NamespacedID) error {
+	// Get the feature
+	feat, err := c.GetFeature(ctx, featureID.Namespace, featureID.ID, false)
+	if err != nil {
+		return err
+	}
+
+	archivedAt := lo.ToPtr(clock.Now())
+
+	// Archive the feature
+	err = c.featureRepo.ArchiveFeature(ctx, ArchiveFeatureInput{
+		Namespace: feat.Namespace,
+		ID:        feat.ID,
+		At:        archivedAt,
+	})
+	if err != nil {
+		return err
+	}
+
+	feat.ArchivedAt = archivedAt
+
+	// Publish the feature archived event
+	featureArchivedEvent := NewFeatureArchiveEvent(ctx, feat)
+	if err := c.publisher.Publish(ctx, featureArchivedEvent); err != nil {
+		return fmt.Errorf("failed to publish feature archived event: %w", err)
+	}
+
+	return nil
+}
+
+// ListFeatures lists features
+func (c *featureConnector) ListFeatures(ctx context.Context, params ListFeaturesParams) (pagination.Result[Feature], error) {
+	if err := params.Validate(); err != nil {
+		return pagination.Result[Feature]{}, err
+	}
+
+	return c.featureRepo.ListFeatures(ctx, params)
+}
+
+// GetFeature gets a feature
+func (c *featureConnector) GetFeature(ctx context.Context, namespace string, idOrKey string, includeArchived IncludeArchivedFeature) (*Feature, error) {
+	feature, err := c.featureRepo.GetByIdOrKey(ctx, namespace, idOrKey, bool(includeArchived))
+	if err != nil {
+		return nil, err
+	}
+	return feature, nil
+}

openmeter/productcatalog/feature/connector_test.go

@@ -0,0 +1,66 @@
+package feature
+
+import (
+	"testing"
+
+	"github.com/alpacahq/alpacadecimal"
+	"github.com/oapi-codegen/nullable"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestUpdateFeatureInputsValidate(t *testing.T) {
+	validUnitCost := nullable.NewNullableWithValue(UnitCost{
+		Type: UnitCostTypeManual,
+		Manual: &ManualUnitCost{
+			Amount: alpacadecimal.NewFromFloat(0.05),
+		},
+	})
+
+	t.Run("valid with unit cost", func(t *testing.T) {
+		input := UpdateFeatureInputs{
+			Namespace: "ns",
+			ID:        "feat-1",
+			UnitCost:  validUnitCost,
+		}
+		assert.NoError(t, input.Validate())
+	})
+
+	t.Run("valid with clear unit cost (null)", func(t *testing.T) {
+		input := UpdateFeatureInputs{
+			Namespace: "ns",
+			ID:        "feat-1",
+			UnitCost:  nullable.NewNullNullable[UnitCost](),
+		}
+		assert.NoError(t, input.Validate())
+	})
+
+	t.Run("invalid without unit cost specified", func(t *testing.T) {
+		input := UpdateFeatureInputs{
+			Namespace: "ns",
+			ID:        "feat-1",
+		}
+		err := input.Validate()
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "unitCost is required")
+	})
+
+	t.Run("invalid missing namespace", func(t *testing.T) {
+		input := UpdateFeatureInputs{
+			ID:       "feat-1",
+			UnitCost: validUnitCost,
+		}
+		err := input.Validate()
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "namespace is required")
+	})
+
+	t.Run("invalid missing id", func(t *testing.T) {
+		input := UpdateFeatureInputs{
+			Namespace: "ns",
+			UnitCost:  validUnitCost,
+		}
+		err := input.Validate()
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "id is required")
+	})
+}

openmeter/productcatalog/feature/event.go

@@ -0,0 +1,164 @@
+package feature
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/oklog/ulid/v2"
+
+	"github.com/openmeterio/openmeter/openmeter/event/metadata"
+	"github.com/openmeterio/openmeter/openmeter/session"
+)
+
+const (
+	FeatureEventSubsystem   metadata.EventSubsystem = "feature"
+	FeatureCreateEventName  metadata.EventName      = "feature.created"
+	FeatureUpdateEventName  metadata.EventName      = "feature.updated"
+	FeatureArchiveEventName metadata.EventName      = "feature.archived"
+)
+
+// NewFeatureCreateEvent creates a new feature create event
+func NewFeatureCreateEvent(ctx context.Context, feature *Feature) FeatureCreateEvent {
+	return FeatureCreateEvent{
+		Feature: feature,
+		UserID:  session.GetSessionUserID(ctx),
+	}
+}
+
+// FeatureCreateEvent is an event that is emitted when a feature is created
+type FeatureCreateEvent struct {
+	Feature *Feature `json:"feature"`
+	UserID  *string  `json:"userId,omitempty"`
+}
+
+func (e FeatureCreateEvent) EventName() string {
+	return metadata.GetEventName(metadata.EventType{
+		Subsystem: FeatureEventSubsystem,
+		Name:      FeatureCreateEventName,
+		Version:   "v1",
+	})
+}
+
+func (e FeatureCreateEvent) EventMetadata() metadata.EventMetadata {
+	resourcePath := metadata.ComposeResourcePath(e.Feature.Namespace, metadata.EntityFeature, e.Feature.ID)
+
+	return metadata.EventMetadata{
+		ID:      ulid.Make().String(),
+		Source:  resourcePath,
+		Subject: resourcePath,
+		Time:    e.Feature.CreatedAt,
+	}
+}
+
+func (e FeatureCreateEvent) Validate() error {
+	var errs []error
+
+	if e.Feature == nil {
+		return fmt.Errorf("feature is required")
+	}
+
+	if err := e.Feature.Validate(); err != nil {
+		errs = append(errs, fmt.Errorf("feature: %w", err))
+	}
+
+	return errors.Join(errs...)
+}
+
+// NewFeatureUpdateEvent creates a new feature update event
+func NewFeatureUpdateEvent(ctx context.Context, feature *Feature) FeatureUpdateEvent {
+	return FeatureUpdateEvent{
+		Feature: feature,
+		UserID:  session.GetSessionUserID(ctx),
+	}
+}
+
+// FeatureUpdateEvent is an event that is emitted when a feature is updated
+type FeatureUpdateEvent struct {
+	Feature *Feature `json:"feature"`
+	UserID  *string  `json:"userId,omitempty"`
+}
+
+func (e FeatureUpdateEvent) EventName() string {
+	return metadata.GetEventName(metadata.EventType{
+		Subsystem: FeatureEventSubsystem,
+		Name:      FeatureUpdateEventName,
+		Version:   "v1",
+	})
+}
+
+func (e FeatureUpdateEvent) EventMetadata() metadata.EventMetadata {
+	resourcePath := metadata.ComposeResourcePath(e.Feature.Namespace, metadata.EntityFeature, e.Feature.ID)
+
+	return metadata.EventMetadata{
+		ID:      ulid.Make().String(),
+		Source:  resourcePath,
+		Subject: resourcePath,
+		Time:    e.Feature.UpdatedAt,
+	}
+}
+
+func (e FeatureUpdateEvent) Validate() error {
+	var errs []error
+
+	if e.Feature == nil {
+		return fmt.Errorf("feature is required")
+	}
+
+	if err := e.Feature.Validate(); err != nil {
+		errs = append(errs, fmt.Errorf("feature: %w", err))
+	}
+
+	return errors.Join(errs...)
+}
+
+// NewFeatureArchiveEvent creates a new feature delete event
+func NewFeatureArchiveEvent(ctx context.Context, feature *Feature) FeatureArchiveEvent {
+	return FeatureArchiveEvent{
+		Feature: feature,
+		UserID:  session.GetSessionUserID(ctx),
+	}
+}
+
+// FeatureArchiveEvent is an event that is emitted when a feature is archived
+type FeatureArchiveEvent struct {
+	Feature *Feature `json:"feature"`
+	UserID  *string  `json:"userId,omitempty"`
+}
+
+func (e FeatureArchiveEvent) EventName() string {
+	return metadata.GetEventName(metadata.EventType{
+		Subsystem: FeatureEventSubsystem,
+		Name:      FeatureArchiveEventName,
+		Version:   "v1",
+	})
+}
+
+func (e FeatureArchiveEvent) EventMetadata() metadata.EventMetadata {
+	resourcePath := metadata.ComposeResourcePath(e.Feature.Namespace, metadata.EntityFeature, e.Feature.ID)
+
+	return metadata.EventMetadata{
+		ID:      ulid.Make().String(),
+		Source:  resourcePath,
+		Subject: resourcePath,
+		Time:    *e.Feature.ArchivedAt,
+	}
+}
+
+func (e FeatureArchiveEvent) Validate() error {
+	var errs []error
+
+	if e.Feature == nil {
+		return fmt.Errorf("feature is required")
+	}
+
+	if e.Feature.ArchivedAt == nil {
+		return fmt.Errorf("feature archived at is required")
+	}
+
+	if err := e.Feature.Validate(); err != nil {
+		errs = append(errs, fmt.Errorf("feature: %w", err))
+	}
+
+	return errors.Join(errs...)
+}

openmeter/productcatalog/feature/feature.go

@@ -0,0 +1,198 @@
+package feature
+
+import (
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/pkg/filter"
+)
+
+type FeatureNotFoundError struct {
+	ID string
+}
+
+func (e *FeatureNotFoundError) Error() string {
+	return fmt.Sprintf("feature not found: %s", e.ID)
+}
+
+type FeatureInvalidFiltersError struct {
+	RequestedFilters    MeterGroupByFilters
+	MeterGroupByColumns []string
+}
+
+func (e *FeatureInvalidFiltersError) Error() string {
+	return fmt.Sprintf("invalid filters for feature: %v, available columns: %v", e.RequestedFilters, e.MeterGroupByColumns)
+}
+
+type FeatureWithNameAlreadyExistsError struct {
+	Name string
+	ID   string
+}
+
+func (e *FeatureWithNameAlreadyExistsError) Error() string {
+	// Is it an issue that we leak ID on another Feature here?
+	// Shouldn't be an isue as it's namespaced.
+	return fmt.Sprintf("feature %s with key %s already exists", e.ID, e.Name)
+}
+
+type FeatureInvalidMeterAggregationError struct {
+	MeterSlug         string
+	Aggregation       meter.MeterAggregation
+	ValidAggregations []meter.MeterAggregation
+}
+
+func (e *FeatureInvalidMeterAggregationError) Error() string {
+	validAggregations := ""
+	for i, validAggregation := range e.ValidAggregations {
+		if i > 0 {
+			validAggregations += ", "
+		}
+		validAggregations += string(validAggregation)
+	}
+	return fmt.Sprintf("meter %s's aggregation is %s but features can only be created for %s", e.MeterSlug, e.Aggregation, validAggregations)
+}
+
+type ForbiddenError struct {
+	Msg string
+	ID  string
+}
+
+func (e *ForbiddenError) Error() string {
+	return fmt.Sprintf("forbidden for feature %s: %s", e.ID, e.Msg)
+}
+
+// MeterGroupByFilters is a map of filters that can be applied to a meter when querying the usage for a feature.
+type MeterGroupByFilters map[string]filter.FilterString
+
+func (f MeterGroupByFilters) Validate(meter meter.Meter) error {
+	for filterProp, filterValue := range f {
+		if _, ok := meter.GroupBy[filterProp]; !ok {
+			meterGroupByColumns := make([]string, 0, len(meter.GroupBy))
+			for k := range meter.GroupBy {
+				meterGroupByColumns = append(meterGroupByColumns, k)
+			}
+			return &FeatureInvalidFiltersError{
+				RequestedFilters:    f,
+				MeterGroupByColumns: meterGroupByColumns,
+			}
+		}
+
+		if err := filterValue.Validate(); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// ConvertMapStringToMeterGroupByFilters converts a map[string]string legacy format to MeterGroupByFilters
+func ConvertMapStringToMeterGroupByFilters(m map[string]string) MeterGroupByFilters {
+	if m == nil {
+		return MeterGroupByFilters{}
+	}
+
+	result := make(MeterGroupByFilters, len(m))
+	for k, v := range m {
+		result[k] = filter.FilterString{Eq: &v}
+	}
+
+	return result
+}
+
+// ConvertMeterGroupByFiltersToMapString converts a MeterGroupByFilters to a legacy map[string]string format
+// if all filters are equality filters, otherwise returns nil.
+func ConvertMeterGroupByFiltersToMapString(f MeterGroupByFilters) map[string]string {
+	if f == nil {
+		return nil
+	}
+
+	result := make(map[string]string, len(f))
+	for k, v := range f {
+		if v.Eq == nil {
+			return nil
+		}
+		result[k] = *v.Eq
+	}
+
+	return result
+}
+
+// Feature is a feature or service offered to a customer.
+// For example: CPU-Hours, Tokens, API Calls, etc.
+type Feature struct {
+	Namespace string `json:"namespace"`
+	ID        string `json:"id,omitempty"`
+
+	// Name The name of the feature.
+	Name string `json:"name"`
+	// Description Optional description of the feature.
+	Description *string `json:"description,omitempty"`
+	// Key The unique key of the feature.
+	Key string `json:"key"`
+
+	// MeterID The ID of the meter that the feature is associated with.
+	MeterID *string `json:"meterID,omitempty"`
+
+	// Deprecated: MeterSlug is kept temporarily for v1 API backward compatibility. Use MeterID.
+	MeterSlug *string `json:"meterSlug,omitempty"`
+
+	// MeterGroupByFilters Optional meter group by filters. Useful if the meter scope is broader than what feature tracks.
+	MeterGroupByFilters MeterGroupByFilters `json:"meterGroupByFilters,omitempty"`
+
+	// UnitCost is an optional per-unit cost: either a fixed manual amount or dynamic LLM cost lookup.
+	UnitCost *UnitCost `json:"unitCost,omitempty"`
+
+	// Metadata Additional metadata.
+	Metadata map[string]string `json:"metadata,omitempty"`
+
+	// Read-only fields
+	ArchivedAt *time.Time `json:"archivedAt,omitempty"`
+
+	CreatedAt time.Time `json:"createdAt"`
+	UpdatedAt time.Time `json:"updatedAt"`
+}
+
+// Validate validates the feature.
+func (f *Feature) Validate() error {
+	var errs []error
+
+	if f.Namespace == "" {
+		errs = append(errs, fmt.Errorf("namespace is required"))
+	}
+
+	if f.ID == "" {
+		errs = append(errs, fmt.Errorf("id is required"))
+	}
+
+	if f.Name == "" {
+		errs = append(errs, fmt.Errorf("name is required"))
+	}
+
+	if f.Key == "" {
+		errs = append(errs, fmt.Errorf("key is required"))
+	}
+
+	if f.MeterID != nil {
+		if *f.MeterID == "" {
+			errs = append(errs, fmt.Errorf("meter id cannot be empty"))
+		}
+	}
+
+	if f.CreatedAt.IsZero() {
+		errs = append(errs, fmt.Errorf("created at is required"))
+	}
+
+	if f.UpdatedAt.IsZero() {
+		errs = append(errs, fmt.Errorf("updated at is required"))
+	}
+
+	if f.UnitCost != nil {
+		if err := f.UnitCost.Validate(); err != nil {
+			errs = append(errs, fmt.Errorf("unit cost is invalid: %w", err))
+		}
+	}
+
+	return errors.Join(errs...)
+}

openmeter/productcatalog/feature/featuremeter.go

@@ -0,0 +1,224 @@
+package feature
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/samber/lo"
+
+	"github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/ref"
+)
+
+type FeatureMeter struct {
+	Feature Feature
+	Meter   *meter.Meter
+}
+
+type FeatureMeters interface {
+	Get(featureKey string, requireMeter bool) (FeatureMeter, error)
+	GetByID(featureID string, requireMeter bool) (FeatureMeter, error)
+}
+
+type FeatureMeterCollection struct {
+	ByKey map[string]FeatureMeter
+	ByID  map[string]FeatureMeter
+}
+
+func (f FeatureMeterCollection) Get(featureKey string, requireMeter bool) (FeatureMeter, error) {
+	featureMeter, exists := f.ByKey[featureKey]
+	if !exists {
+		return FeatureMeter{}, models.NewGenericNotFoundError(fmt.Errorf("feature[%s] not found", featureKey))
+	}
+
+	if requireMeter && featureMeter.Meter == nil {
+		return FeatureMeter{}, models.NewGenericValidationError(fmt.Errorf("feature[%s] has no meter associated", featureMeter.Feature.Key))
+	}
+
+	return featureMeter, nil
+}
+
+func (f FeatureMeterCollection) GetByID(featureID string, requireMeter bool) (FeatureMeter, error) {
+	featureMeter, exists := f.ByID[featureID]
+	if !exists {
+		return FeatureMeter{}, models.NewGenericNotFoundError(fmt.Errorf("feature[%s] not found", featureID))
+	}
+
+	if requireMeter && featureMeter.Meter == nil {
+		return FeatureMeter{}, models.NewGenericValidationError(fmt.Errorf("feature[%s] has no meter associated", featureMeter.Feature.Key))
+	}
+
+	return featureMeter, nil
+}
+
+func (c *featureConnector) ResolveFeatureMeters(ctx context.Context, namespace string, featureRefs ...ref.IDOrKey) (FeatureMeters, error) {
+	if namespace == "" {
+		return nil, fmt.Errorf("namespace is required")
+	}
+
+	if len(featureRefs) == 0 {
+		return FeatureMeterCollection{
+			ByKey: map[string]FeatureMeter{},
+			ByID:  map[string]FeatureMeter{},
+		}, nil
+	}
+
+	featuresToResolve := lo.Uniq(lo.FlatMap(featureRefs, func(featureRef ref.IDOrKey, _ int) []string {
+		out := featureRef.GetKeys()
+		out = append(out, featureRef.GetIDs()...)
+		return out
+	}))
+
+	// Let's resolve the features
+	features, err := c.featureRepo.ListFeatures(ctx, ListFeaturesParams{
+		IDsOrKeys:       featuresToResolve,
+		Namespace:       namespace,
+		IncludeArchived: true,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("listing features: %w", err)
+	}
+
+	out := resolveFeatureMeters(features.Items)
+	if err := ensureFeatureIDsResolved(featureRefs, out); err != nil {
+		return nil, err
+	}
+
+	metersToResolve := lo.Uniq(
+		lo.Filter(
+			lo.Map(lo.Values(out.ByID), func(fm FeatureMeter, _ int) string {
+				f := fm.Feature
+				if f.MeterID == nil {
+					return ""
+				}
+
+				return *f.MeterID
+			}),
+			func(meterID string, _ int) bool {
+				return meterID != ""
+			},
+		),
+	)
+
+	meters, err := c.meterService.ListMeters(ctx, meter.ListMetersParams{
+		IDFilter:       lo.ToPtr(metersToResolve),
+		Namespace:      namespace,
+		IncludeDeleted: true,
+	})
+	if err != nil {
+		return nil, fmt.Errorf("listing meters: %w", err)
+	}
+
+	metersByID := lo.SliceToMap(meters.Items, func(m meter.Meter) (string, meter.Meter) {
+		return m.ID, m
+	})
+
+	for featureID, featureMeter := range out.ByID {
+		if featureMeter.Feature.MeterID == nil {
+			out.ByID[featureID] = featureMeter
+			continue
+		}
+
+		meter, exists := metersByID[*featureMeter.Feature.MeterID]
+		if exists {
+			featureMeter.Meter = &meter
+		}
+
+		out.ByID[featureID] = featureMeter
+		if latest, ok := out.ByKey[featureMeter.Feature.Key]; ok && latest.Feature.ID == featureID {
+			out.ByKey[featureMeter.Feature.Key] = featureMeter
+		}
+	}
+
+	return out, nil
+}
+
+func resolveFeatureMeters(features []Feature) FeatureMeterCollection {
+	featuresByKey := getLastFeatures(features)
+
+	out := FeatureMeterCollection{
+		ByKey: make(map[string]FeatureMeter, len(featuresByKey)),
+		ByID:  make(map[string]FeatureMeter, len(features)),
+	}
+
+	for _, feat := range features {
+		out.ByID[feat.ID] = FeatureMeter{
+			Feature: feat,
+		}
+	}
+
+	for featureKey, feat := range featuresByKey {
+		out.ByKey[featureKey] = out.ByID[feat.ID]
+	}
+
+	return out
+}
+
+func ensureFeatureIDsResolved(featureRefs []ref.IDOrKey, resolved FeatureMeterCollection) error {
+	for _, featureID := range lo.Uniq(lo.FlatMap(featureRefs, func(featureRef ref.IDOrKey, _ int) []string {
+		return featureRef.GetIDs()
+	})) {
+		if _, ok := resolved.ByID[featureID]; !ok {
+			return models.NewGenericNotFoundError(fmt.Errorf("feature[%s] not found", featureID))
+		}
+	}
+
+	return nil
+}
+
+type lastEntityAccessor[T any] interface {
+	GetKey(T) string
+	GetDeletedAt(T) *time.Time
+}
+
+func getLastEntity[T any](entities []T, accessor lastEntityAccessor[T]) map[string]T {
+	featuresByKey := lo.GroupBy(entities, func(entity T) string {
+		return accessor.GetKey(entity)
+	})
+
+	out := make(map[string]T, len(featuresByKey))
+	for key, features := range featuresByKey {
+		// Let's try to find an unarchived feature
+		out[key] = latestEntity(features, accessor)
+	}
+
+	return out
+}
+
+func latestEntity[T any](entities []T, accessor lastEntityAccessor[T]) T {
+	for _, entity := range entities {
+		if accessor.GetDeletedAt(entity) == nil {
+			return entity
+		}
+	}
+
+	// Otherwise, let's find the most recently archived feature:
+	// - all entities have non-nil deleted at (or we would have returned already)
+	// - and we have at least one entity due to the definition of the groupBy
+	mostRecentlyArchivedFeature := entities[0]
+	for _, entity := range entities {
+		if accessor.GetDeletedAt(entity).After(*accessor.GetDeletedAt(mostRecentlyArchivedFeature)) {
+			mostRecentlyArchivedFeature = entity
+		}
+	}
+
+	return mostRecentlyArchivedFeature
+}
+
+type featureAccessor struct{}
+
+var _ lastEntityAccessor[Feature] = (*featureAccessor)(nil)
+
+func (a featureAccessor) GetKey(f Feature) string {
+	return f.Key
+}
+
+func (a featureAccessor) GetDeletedAt(f Feature) *time.Time {
+	return f.ArchivedAt
+}
+
+func getLastFeatures(features []Feature) map[string]Feature {
+	return getLastEntity(features, featureAccessor{})
+}

openmeter/productcatalog/feature/featuremeter_test.go

@@ -0,0 +1,108 @@
+package feature
+
+import (
+	"testing"
+	"time"
+
+	"github.com/samber/lo"
+	"github.com/stretchr/testify/require"
+
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/ref"
+)
+
+func TestGetLastFeatures(t *testing.T) {
+	tcs := []struct {
+		name     string
+		features []Feature
+		expected map[string]string
+	}{
+		{
+			name: "single-active",
+			features: []Feature{
+				{ID: "id-active", ArchivedAt: nil, Key: "feature-1-active"},
+			},
+			expected: map[string]string{"feature-1-active": "id-active"},
+		},
+		{
+			name: "single-archived",
+			features: []Feature{
+				{ID: "id-archived", ArchivedAt: lo.ToPtr(time.Now()), Key: "feature-1-archived"},
+			},
+			expected: map[string]string{"feature-1-archived": "id-archived"},
+		},
+		{
+			name: "multi-archived",
+			features: []Feature{
+				{ID: "id-archived", ArchivedAt: lo.ToPtr(time.Now()), Key: "feature-1"},
+				{ID: "id-active", ArchivedAt: nil, Key: "feature-1"},
+			},
+			expected: map[string]string{"feature-1": "id-active"},
+		},
+		{
+			name: "archived-ordering",
+			features: []Feature{
+				{ID: "id-archived-1", ArchivedAt: lo.ToPtr(time.Now()), Key: "feature-1"},
+				{ID: "id-archived-2", ArchivedAt: lo.ToPtr(time.Now().Add(5 * time.Second)), Key: "feature-1"},
+			},
+			expected: map[string]string{"feature-1": "id-archived-2"},
+		},
+	}
+
+	for _, tc := range tcs {
+		t.Run(tc.name, func(t *testing.T) {
+			out := getLastFeatures(tc.features)
+
+			featureKeyToID := map[string]string{}
+			for key, feat := range out {
+				featureKeyToID[key] = feat.ID
+			}
+
+			require.Equal(t, tc.expected, featureKeyToID)
+		})
+	}
+}
+
+func TestResolveFeatureMeters(t *testing.T) {
+	archivedAt := time.Now()
+
+	features := []Feature{
+		{ID: "feature-old", Key: "tokens", ArchivedAt: &archivedAt},
+		{ID: "feature-new", Key: "tokens", ArchivedAt: nil},
+		{ID: "feature-other", Key: "requests", ArchivedAt: nil},
+	}
+
+	t.Run("key resolves latest while explicit ids remain addressable", func(t *testing.T) {
+		out := resolveFeatureMeters(features)
+
+		byKey, err := out.Get("tokens", false)
+		require.NoError(t, err)
+		require.Equal(t, "feature-new", byKey.Feature.ID)
+
+		byLatestID, err := out.GetByID("feature-new", false)
+		require.NoError(t, err)
+		require.Equal(t, "feature-new", byLatestID.Feature.ID)
+
+		byArchivedID, err := out.GetByID("feature-old", false)
+		require.NoError(t, err)
+		require.Equal(t, "feature-old", byArchivedID.Feature.ID)
+		require.Equal(t, "tokens", byArchivedID.Feature.Key)
+	})
+
+	t.Run("requested ids must all resolve", func(t *testing.T) {
+		out := resolveFeatureMeters(features)
+
+		require.NoError(t, ensureFeatureIDsResolved([]ref.IDOrKey{
+			{ID: "feature-old"},
+			{ID: "feature-new"},
+		}, out))
+
+		err := ensureFeatureIDsResolved([]ref.IDOrKey{
+			{ID: "feature-old"},
+			{ID: "missing-feature"},
+		}, out)
+		require.Error(t, err)
+		require.True(t, models.IsGenericNotFoundError(err))
+		require.ErrorContains(t, err, "missing-feature")
+	})
+}

openmeter/productcatalog/feature/meter_group_by_filters_test.go

@@ -0,0 +1,50 @@
+package feature
+
+import (
+	"testing"
+
+	"github.com/samber/lo"
+	"github.com/stretchr/testify/require"
+
+	"github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/pkg/filter"
+)
+
+func TestMeterGroupByFiltersValidate(t *testing.T) {
+	m := meter.Meter{
+		Key: "tokens_total",
+		GroupBy: map[string]string{
+			"provider": "$.provider",
+			"model":    "$.model",
+		},
+	}
+
+	t.Run("valid single operator", func(t *testing.T) {
+		f := MeterGroupByFilters{
+			"provider": filter.FilterString{Eq: lo.ToPtr("openai")},
+		}
+
+		require.NoError(t, f.Validate(m))
+	})
+
+	t.Run("unknown dimension key", func(t *testing.T) {
+		f := MeterGroupByFilters{
+			"nonexistent": filter.FilterString{Eq: lo.ToPtr("value")},
+		}
+
+		err := f.Validate(m)
+		require.Error(t, err)
+	})
+
+	t.Run("multiple operators on a single filter rejected", func(t *testing.T) {
+		f := MeterGroupByFilters{
+			"provider": filter.FilterString{
+				Eq: lo.ToPtr("openai"),
+				Ne: lo.ToPtr("anthropic"),
+			},
+		}
+
+		err := f.Validate(m)
+		require.Error(t, err)
+	})
+}

openmeter/productcatalog/feature/repository.go

@@ -0,0 +1,47 @@
+package feature
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"github.com/openmeterio/openmeter/pkg/framework/entutils"
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+)
+
+type ArchiveFeatureInput struct {
+	Namespace string
+	ID        string
+	At        *time.Time
+}
+
+func (i ArchiveFeatureInput) Validate() error {
+	var errs []error
+
+	if i.Namespace == "" {
+		errs = append(errs, errors.New("namespace is required"))
+	}
+
+	if i.ID == "" {
+		errs = append(errs, errors.New("id is required"))
+	}
+
+	if i.At != nil && i.At.IsZero() {
+		errs = append(errs, errors.New("at must not be zero"))
+	}
+
+	return models.NewNillableGenericValidationError(errors.Join(errs...))
+}
+
+type FeatureRepo interface {
+	CreateFeature(ctx context.Context, feature CreateFeatureInputs) (Feature, error)
+	UpdateFeature(ctx context.Context, input UpdateFeatureInputs) (Feature, error)
+	ArchiveFeature(ctx context.Context, params ArchiveFeatureInput) error
+	ListFeatures(ctx context.Context, params ListFeaturesParams) (pagination.Result[Feature], error)
+	HasActiveFeatureForMeter(ctx context.Context, namespace string, meterID string) (bool, error)
+
+	GetByIdOrKey(ctx context.Context, namespace string, idOrKey string, includeArchived bool) (*Feature, error)
+	entutils.TxCreator
+	entutils.TxUser[FeatureRepo]
+}

openmeter/productcatalog/feature/unitcost.go

@@ -0,0 +1,187 @@
+package feature
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/alpacahq/alpacadecimal"
+
+	"github.com/openmeterio/openmeter/openmeter/meter"
+)
+
+// UnitCostType identifies the type of unit cost.
+type UnitCostType string
+
+const (
+	UnitCostTypeLLM    UnitCostType = "llm"
+	UnitCostTypeManual UnitCostType = "manual"
+)
+
+// UnitCost represents an optional per-unit cost configuration for a feature.
+type UnitCost struct {
+	// Type is the unit cost type: "llm" or "manual".
+	Type UnitCostType `json:"type"`
+
+	// Manual is set when type is "manual".
+	Manual *ManualUnitCost `json:"manual,omitempty"`
+
+	// LLM is set when type is "llm".
+	LLM *LLMUnitCost `json:"llm,omitempty"`
+}
+
+// ManualUnitCost is a fixed per-unit cost amount.
+type ManualUnitCost struct {
+	// Amount is the per-unit cost in USD.
+	Amount alpacadecimal.Decimal `json:"amount"`
+}
+
+// LLMUnitCost configures dynamic cost lookup from the LLM cost database.
+// For each dimension (provider, model, token type), either a static value
+// or a meter group-by property name can be specified (mutually exclusive).
+type LLMUnitCost struct {
+	// ProviderProperty is the meter group-by key that holds the LLM provider value.
+	// Mutually exclusive with Provider.
+	ProviderProperty string `json:"provider_property,omitempty"`
+
+	// Provider is a static LLM provider value (e.g. "openai", "anthropic").
+	// Mutually exclusive with ProviderProperty.
+	Provider string `json:"provider,omitempty"`
+
+	// ModelProperty is the meter group-by key that holds the model ID value.
+	// Mutually exclusive with Model.
+	ModelProperty string `json:"model_property,omitempty"`
+
+	// Model is a static model ID value (e.g. "gpt-4", "claude-3-5-sonnet").
+	// Mutually exclusive with ModelProperty.
+	Model string `json:"model,omitempty"`
+
+	// TokenTypeProperty is the meter group-by key that holds the token type.
+	// Mutually exclusive with TokenType.
+	TokenTypeProperty string `json:"token_type_property,omitempty"`
+
+	// TokenType is a static token type value (e.g. "input", "output").
+	// Use this when the feature tracks a single token type.
+	// Mutually exclusive with TokenTypeProperty.
+	TokenType string `json:"token_type,omitempty"`
+}
+
+// Validate validates the unit cost configuration.
+func (u *UnitCost) Validate() error {
+	if u == nil {
+		return nil
+	}
+
+	switch u.Type {
+	case UnitCostTypeManual:
+		if u.Manual == nil {
+			return errors.New("manual unit cost configuration is required when type is manual")
+		}
+
+		if u.LLM != nil {
+			return errors.New("llm configuration must not be set when type is manual")
+		}
+
+		if u.Manual.Amount.IsNegative() {
+			return errors.New("manual unit cost amount must be non-negative")
+		}
+
+		return nil
+
+	case UnitCostTypeLLM:
+		if u.LLM == nil {
+			return errors.New("LLM unit cost configuration is required when type is llm")
+		}
+
+		if u.Manual != nil {
+			return errors.New("manual configuration must not be set when type is llm")
+		}
+
+		var errs []error
+
+		// Provider: exactly one of property or static value
+		if u.LLM.ProviderProperty == "" && u.LLM.Provider == "" {
+			errs = append(errs, errors.New("either provider_property or provider is required for LLM unit cost"))
+		}
+		if u.LLM.ProviderProperty != "" && u.LLM.Provider != "" {
+			errs = append(errs, errors.New("provider_property and provider are mutually exclusive"))
+		}
+
+		// Model: exactly one of property or static value
+		if u.LLM.ModelProperty == "" && u.LLM.Model == "" {
+			errs = append(errs, errors.New("either model_property or model is required for LLM unit cost"))
+		}
+		if u.LLM.ModelProperty != "" && u.LLM.Model != "" {
+			errs = append(errs, errors.New("model_property and model are mutually exclusive"))
+		}
+
+		// Token type: exactly one of property or static value
+		if u.LLM.TokenTypeProperty == "" && u.LLM.TokenType == "" {
+			errs = append(errs, errors.New("either token_type_property or token_type is required for LLM unit cost"))
+		}
+		if u.LLM.TokenTypeProperty != "" && u.LLM.TokenType != "" {
+			errs = append(errs, errors.New("token_type_property and token_type are mutually exclusive"))
+		}
+
+		if u.LLM.TokenType != "" {
+			validTypes := map[LLMTokenType]bool{
+				LLMTokenTypeInput: true, LLMTokenTypeOutput: true,
+				LLMTokenTypeCacheRead: true, LLMTokenTypeReasoning: true,
+				LLMTokenTypeCacheWrite: true,
+				LLMTokenTypeRequest:    true, LLMTokenTypeResponse: true,
+			}
+			if !validTypes[LLMTokenType(u.LLM.TokenType)] {
+				errs = append(errs, fmt.Errorf("invalid token_type %q: expected one of input, output, cache_read, reasoning, cache_write, request, response", u.LLM.TokenType))
+			}
+		}
+
+		return errors.Join(errs...)
+
+	default:
+		return fmt.Errorf("invalid unit cost type: %s", u.Type)
+	}
+}
+
+// ValidateWithMeter validates that the LLM unit cost property names exist in the meter's GroupBy keys.
+func (u *UnitCost) ValidateWithMeter(m meter.Meter) error {
+	if u == nil || u.Type != UnitCostTypeLLM || u.LLM == nil {
+		return nil
+	}
+
+	var errs []error
+
+	if u.LLM.ProviderProperty != "" {
+		if _, ok := m.GroupBy[u.LLM.ProviderProperty]; !ok {
+			errs = append(errs, fmt.Errorf("provider_property %q not found in meter group-by keys", u.LLM.ProviderProperty))
+		}
+	}
+
+	if u.LLM.ModelProperty != "" {
+		if _, ok := m.GroupBy[u.LLM.ModelProperty]; !ok {
+			errs = append(errs, fmt.Errorf("model_property %q not found in meter group-by keys", u.LLM.ModelProperty))
+		}
+	}
+
+	if u.LLM.TokenTypeProperty != "" {
+		if _, ok := m.GroupBy[u.LLM.TokenTypeProperty]; !ok {
+			errs = append(errs, fmt.Errorf("token_type_property %q not found in meter group-by keys", u.LLM.TokenTypeProperty))
+		}
+	}
+
+	return errors.Join(errs...)
+}
+
+// LLMTokenType identifies a token dimension for LLM pricing.
+type LLMTokenType string
+
+const (
+	LLMTokenTypeInput      LLMTokenType = "input"
+	LLMTokenTypeOutput     LLMTokenType = "output"
+	LLMTokenTypeCacheRead  LLMTokenType = "cache_read"
+	LLMTokenTypeCacheWrite LLMTokenType = "cache_write"
+	LLMTokenTypeReasoning  LLMTokenType = "reasoning"
+
+	// LLMTokenTypeRequest is an alias for input tokens used by some providers.
+	LLMTokenTypeRequest LLMTokenType = "request"
+	// LLMTokenTypeResponse is an alias for output tokens used by some providers.
+	LLMTokenTypeResponse LLMTokenType = "response"
+)

openmeter/productcatalog/featureresolver.go

@@ -0,0 +1,19 @@
+package productcatalog
+
+import (
+	"context"
+
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+)
+
+type FeatureResolver interface {
+	Resolve(ctx context.Context, namespace string, id, key *string) (*feature.Feature, error)
+	BatchResolve(ctx context.Context, namespace string, idOrKeys ...string) (map[string]*feature.Feature, error)
+	WithNamespace(namespace string) NamespacedFeatureResolver
+}
+
+type NamespacedFeatureResolver interface {
+	Resolve(ctx context.Context, id, key *string) (*feature.Feature, error)
+	BatchResolve(ctx context.Context, idOrKeys ...string) (map[string]*feature.Feature, error)
+	Namespace() string
+}

openmeter/productcatalog/featureresolver/ratecard.go

@@ -0,0 +1,122 @@
+package featureresolver
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/samber/lo"
+
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+func ResolveFeaturesForRateCards(
+	ctx context.Context,
+	resolver productcatalog.FeatureResolver,
+	namespace string,
+	rateCards *productcatalog.RateCards,
+) error {
+	if rateCards == nil || len(*rateCards) == 0 {
+		return nil
+	}
+
+	featureIDAndKeys := make([]string, 0, 2*len(*rateCards))
+
+	for _, rc := range *rateCards {
+		if !rc.HasFeature() {
+			continue
+		}
+
+		if id := rc.GetFeatureID(); id != nil && *id != "" {
+			featureIDAndKeys = append(featureIDAndKeys, *id)
+		}
+
+		if key := rc.GetFeatureKey(); key != nil && *key != "" {
+			featureIDAndKeys = append(featureIDAndKeys, *key)
+		}
+	}
+
+	features, err := resolver.BatchResolve(ctx, namespace, featureIDAndKeys...)
+	if err != nil {
+		return fmt.Errorf("failed to resolve features: %w", err)
+	}
+
+	var errs []error
+
+	for _, rc := range *rateCards {
+		if !rc.HasFeature() {
+			continue
+		}
+
+		var f *feature.Feature
+
+		id := rc.GetFeatureID()
+		hasID := id != nil && *id != ""
+
+		key := rc.GetFeatureKey()
+		hasKey := key != nil && *key != ""
+
+		fieldSelector := models.NewFieldSelectorGroup(
+			models.NewFieldSelector("ratecards").WithExpression(
+				models.NewFieldAttrValue("key", rc.Key())),
+		)
+
+		if hasID {
+			f = features[*id]
+
+			if f == nil {
+				errs = append(errs, models.ErrorWithFieldPrefix(fieldSelector,
+					fmt.Errorf("feature not found [ratecard.key=%s feature.id=%s]: %w",
+						rc.Key(), lo.FromPtr(id), productcatalog.ErrRateCardFeatureNotFound),
+				))
+
+				continue
+			}
+
+			if f.ID != *id {
+				errs = append(errs, models.ErrorWithFieldPrefix(fieldSelector,
+					fmt.Errorf("feature id conflict [ratecard.key=%s feature.id=%s feature.key=%s]: %w",
+						rc.Key(), lo.FromPtr(id), lo.FromPtr(key), productcatalog.ErrRateCardFeatureMismatch),
+				))
+
+				continue
+			}
+		}
+
+		if hasKey {
+			if f == nil {
+				f = features[*key]
+			}
+
+			if f == nil {
+				errs = append(errs, models.ErrorWithFieldPrefix(fieldSelector,
+					fmt.Errorf("feature not found [ratecard.key=%s feature.key=%s]: %w",
+						rc.Key(), lo.FromPtr(key), productcatalog.ErrRateCardFeatureNotFound),
+				))
+
+				continue
+			}
+
+			if f.Key != *key {
+				errs = append(errs, models.ErrorWithFieldPrefix(fieldSelector,
+					fmt.Errorf("feature key conflict [ratecard.key=%s feature.id=%s feature.key=%s]: %w",
+						rc.Key(), lo.FromPtr(id), lo.FromPtr(key), productcatalog.ErrRateCardFeatureMismatch),
+				))
+
+				continue
+			}
+		}
+
+		if f == nil {
+			errs = append(errs, models.ErrorWithFieldPrefix(fieldSelector,
+				fmt.Errorf("feature not found [ratecard.key=%s]: %w", rc.Key(), productcatalog.ErrRateCardFeatureNotFound),
+			))
+		} else {
+			rc.SetFeature(&(f).ID, &(f).Key)
+		}
+	}
+
+	return models.NewNillableGenericValidationError(errors.Join(errs...))
+}

openmeter/productcatalog/featureresolver/ratecard_test.go

@@ -0,0 +1,280 @@
+package featureresolver_test
+
+import (
+	"testing"
+
+	decimal "github.com/alpacahq/alpacadecimal"
+	"github.com/samber/lo"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/featureresolver"
+	pctestutils "github.com/openmeterio/openmeter/openmeter/productcatalog/testutils"
+	"github.com/openmeterio/openmeter/pkg/datetime"
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+)
+
+func Test_ResolveFeaturesForRateCards(t *testing.T) {
+	// Setup test environment
+	env := pctestutils.NewTestEnv(t)
+	t.Cleanup(func() {
+		env.Close(t)
+	})
+
+	// Run database migrations
+
+	// Get new namespace ID
+	namespace := pctestutils.NewTestNamespace(t)
+
+	// Setup meter repository
+	err := env.Meter.ReplaceMeters(t.Context(), pctestutils.NewTestMeters(t, namespace))
+	require.NoError(t, err, "replacing meters must not fail")
+
+	result, err := env.Meter.ListMeters(t.Context(), meter.ListMetersParams{
+		Page: pagination.Page{
+			PageSize:   1000,
+			PageNumber: 1,
+		},
+		Namespace: namespace,
+	})
+	require.NoErrorf(t, err, "listing meters must not fail")
+
+	meters := result.Items
+	require.NotEmptyf(t, meters, "list of Meters must not be empty")
+
+	// Set a feature for each meter
+	features := make([]feature.Feature, 0, len(meters))
+	for _, m := range meters {
+		input := pctestutils.NewTestFeatureFromMeter(t, &m)
+
+		feat, err := env.Feature.CreateFeature(t.Context(), input)
+		require.NoErrorf(t, err, "creating feature must not fail")
+		require.NotNil(t, feat, "feature must not be empty")
+
+		features = append(features, feat)
+	}
+	require.NotEmptyf(t, features, "list of Features must not be empty")
+	require.Lenf(t, features, len(meters), "list of Features must have the same length as the list of Meters")
+
+	MonthPeriod := datetime.MustParseDuration(t, "P1M")
+
+	tests := []struct {
+		name        string
+		ratecards   *productcatalog.RateCards
+		expectedErr error
+	}{
+		{
+			name: "success",
+			ratecards: &productcatalog.RateCards{
+				&productcatalog.FlatFeeRateCard{
+					RateCardMeta: productcatalog.RateCardMeta{
+						Key:         features[0].Key,
+						Name:        features[0].Name,
+						Description: lo.ToPtr("RateCard 1"),
+						Metadata:    models.Metadata{"name": features[0].Name},
+						FeatureKey:  lo.ToPtr(features[0].Key),
+						TaxConfig: &productcatalog.TaxConfig{
+							Stripe: &productcatalog.StripeTaxConfig{
+								Code: "txcd_10000000",
+							},
+						},
+						Price: productcatalog.NewPriceFrom(
+							productcatalog.FlatPrice{
+								Amount:      decimal.NewFromInt(0),
+								PaymentTerm: productcatalog.InArrearsPaymentTerm,
+							}),
+					},
+					BillingCadence: &MonthPeriod,
+				},
+				&productcatalog.UsageBasedRateCard{
+					RateCardMeta: productcatalog.RateCardMeta{
+						Key:         features[1].Key,
+						Name:        features[1].Name,
+						Description: lo.ToPtr("RateCard 2"),
+						Metadata:    models.Metadata{"name": features[1].Name},
+						FeatureID:   lo.ToPtr(features[1].ID),
+						TaxConfig: &productcatalog.TaxConfig{
+							Stripe: &productcatalog.StripeTaxConfig{
+								Code: "txcd_10000000",
+							},
+						},
+						Price: productcatalog.NewPriceFrom(
+							productcatalog.TieredPrice{
+								Mode: productcatalog.VolumeTieredPrice,
+								Tiers: []productcatalog.PriceTier{
+									{
+										UpToAmount: lo.ToPtr(decimal.NewFromInt(1000)),
+										FlatPrice: &productcatalog.PriceTierFlatPrice{
+											Amount: decimal.NewFromInt(100),
+										},
+										UnitPrice: &productcatalog.PriceTierUnitPrice{
+											Amount: decimal.NewFromInt(50),
+										},
+									},
+									{
+										UpToAmount: nil,
+										FlatPrice: &productcatalog.PriceTierFlatPrice{
+											Amount: decimal.NewFromInt(75),
+										},
+										UnitPrice: &productcatalog.PriceTierUnitPrice{
+											Amount: decimal.NewFromInt(25),
+										},
+									},
+								},
+								Commitments: productcatalog.Commitments{
+									MinimumAmount: lo.ToPtr(decimal.NewFromInt(1000)),
+									MaximumAmount: nil,
+								},
+							}),
+					},
+					BillingCadence: MonthPeriod,
+				},
+				&productcatalog.FlatFeeRateCard{
+					RateCardMeta: productcatalog.RateCardMeta{
+						Key:         features[2].Key,
+						Name:        features[2].Name,
+						Description: lo.ToPtr("RateCard 3"),
+						Metadata:    models.Metadata{"name": features[2].Name},
+						FeatureKey:  lo.ToPtr(features[2].Key),
+						TaxConfig: &productcatalog.TaxConfig{
+							Stripe: &productcatalog.StripeTaxConfig{
+								Code: "txcd_10000000",
+							},
+						},
+						Price: productcatalog.NewPriceFrom(
+							productcatalog.FlatPrice{
+								Amount:      decimal.NewFromInt(0),
+								PaymentTerm: productcatalog.InArrearsPaymentTerm,
+							}),
+					},
+					BillingCadence: &MonthPeriod,
+				},
+			},
+		},
+		{
+			name: "not found",
+			ratecards: &productcatalog.RateCards{
+				&productcatalog.FlatFeeRateCard{
+					RateCardMeta: productcatalog.RateCardMeta{
+						Key:         "abracadabra",
+						Name:        "abracadabra",
+						Description: lo.ToPtr("RateCard 4"),
+						Metadata:    models.Metadata{"name": "abracadabra"},
+						FeatureKey:  lo.ToPtr("abracadabra"),
+						TaxConfig: &productcatalog.TaxConfig{
+							Stripe: &productcatalog.StripeTaxConfig{
+								Code: "txcd_10000000",
+							},
+						},
+						Price: productcatalog.NewPriceFrom(
+							productcatalog.FlatPrice{
+								Amount:      decimal.NewFromInt(0),
+								PaymentTerm: productcatalog.InArrearsPaymentTerm,
+							}),
+					},
+					BillingCadence: &MonthPeriod,
+				},
+				&productcatalog.FlatFeeRateCard{
+					RateCardMeta: productcatalog.RateCardMeta{
+						Key:         "abracadabra-2",
+						Name:        "abracadabra-2",
+						Description: lo.ToPtr("RateCard 4"),
+						Metadata:    models.Metadata{"name": "abracadabra-2"},
+						FeatureID:   lo.ToPtr("abracadabra-2"),
+						TaxConfig: &productcatalog.TaxConfig{
+							Stripe: &productcatalog.StripeTaxConfig{
+								Code: "txcd_10000000",
+							},
+						},
+						Price: productcatalog.NewPriceFrom(
+							productcatalog.FlatPrice{
+								Amount:      decimal.NewFromInt(0),
+								PaymentTerm: productcatalog.InArrearsPaymentTerm,
+							}),
+					},
+					BillingCadence: &MonthPeriod,
+				},
+			},
+			expectedErr: productcatalog.ErrRateCardFeatureNotFound,
+		},
+		{
+			name: "mismatch",
+			ratecards: &productcatalog.RateCards{
+				&productcatalog.FlatFeeRateCard{
+					RateCardMeta: productcatalog.RateCardMeta{
+						Key:         features[0].Key,
+						Name:        features[0].Name,
+						Description: lo.ToPtr("RateCard 4"),
+						Metadata:    models.Metadata{"name": features[0].Name},
+						FeatureKey:  lo.ToPtr(features[0].Key),
+						FeatureID:   lo.ToPtr(features[1].ID),
+						TaxConfig: &productcatalog.TaxConfig{
+							Stripe: &productcatalog.StripeTaxConfig{
+								Code: "txcd_10000000",
+							},
+						},
+						Price: productcatalog.NewPriceFrom(
+							productcatalog.FlatPrice{
+								Amount:      decimal.NewFromInt(0),
+								PaymentTerm: productcatalog.InArrearsPaymentTerm,
+							}),
+					},
+					BillingCadence: &MonthPeriod,
+				},
+			},
+			expectedErr: productcatalog.ErrRateCardFeatureMismatch,
+		},
+		{
+			name: "id is actually a key",
+			ratecards: &productcatalog.RateCards{
+				&productcatalog.FlatFeeRateCard{
+					RateCardMeta: productcatalog.RateCardMeta{
+						Key:       features[0].Key,
+						Name:      features[0].Name,
+						FeatureID: lo.ToPtr(features[0].Key), // wrong slot
+						Price:     productcatalog.NewPriceFrom(productcatalog.FlatPrice{Amount: decimal.NewFromInt(0), PaymentTerm: productcatalog.InArrearsPaymentTerm}),
+					},
+					BillingCadence: &MonthPeriod,
+				},
+			},
+			expectedErr: productcatalog.ErrRateCardFeatureMismatch,
+		},
+		{
+			name: "key is actually an id",
+			ratecards: &productcatalog.RateCards{
+				&productcatalog.FlatFeeRateCard{
+					RateCardMeta: productcatalog.RateCardMeta{
+						Key:        features[0].Key,
+						Name:       features[0].Name,
+						FeatureKey: lo.ToPtr(features[0].ID), // wrong slot
+						Price:      productcatalog.NewPriceFrom(productcatalog.FlatPrice{Amount: decimal.NewFromInt(0), PaymentTerm: productcatalog.InArrearsPaymentTerm}),
+					},
+					BillingCadence: &MonthPeriod,
+				},
+			},
+			expectedErr: productcatalog.ErrRateCardFeatureMismatch,
+		},
+	}
+
+	resolver, err := featureresolver.New(env.Feature)
+	require.NoError(t, err, "creating feature resolver must not fail")
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			err = featureresolver.ResolveFeaturesForRateCards(t.Context(), resolver, namespace, test.ratecards)
+			if test.expectedErr != nil {
+				require.Error(t, err, "expected error")
+				assert.ErrorIsf(t, err, test.expectedErr, "expected error message")
+			} else {
+				for idx, rc := range *test.ratecards {
+					assert.Equal(t, features[idx].ID, lo.FromPtr(rc.GetFeatureID()), "resolved feature id must be equal to the one we set")
+					assert.Equal(t, features[idx].Key, lo.FromPtr(rc.GetFeatureKey()), "resolved feature key must be equal to the one we set")
+				}
+			}
+		})
+	}
+}

openmeter/productcatalog/featureresolver/resolver.go

@@ -0,0 +1,156 @@
+package featureresolver
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	"github.com/samber/lo"
+
+	"github.com/openmeterio/openmeter/openmeter/productcatalog"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+)
+
+// NOTE: this should live under the feature package after it gets refactored
+
+func New(service feature.FeatureConnector) (productcatalog.FeatureResolver, error) {
+	if service == nil {
+		return nil, errors.New("feature connector is not set")
+	}
+
+	return &resolver{
+		service: service,
+	}, nil
+}
+
+var _ productcatalog.NamespacedFeatureResolver = (*namespacedResolver)(nil)
+
+type namespacedResolver struct {
+	resolver  *resolver
+	namespace string
+}
+
+func (n *namespacedResolver) Namespace() string {
+	return n.namespace
+}
+
+func (n *namespacedResolver) Resolve(ctx context.Context, id, key *string) (*feature.Feature, error) {
+	return n.resolver.Resolve(ctx, n.namespace, id, key)
+}
+
+func (n *namespacedResolver) BatchResolve(ctx context.Context, idOrKeys ...string) (map[string]*feature.Feature, error) {
+	return n.resolver.BatchResolve(ctx, n.namespace, idOrKeys...)
+}
+
+var _ productcatalog.FeatureResolver = (*resolver)(nil)
+
+type resolver struct {
+	service feature.FeatureConnector
+}
+
+func (r *resolver) WithNamespace(namespace string) productcatalog.NamespacedFeatureResolver {
+	return &namespacedResolver{
+		resolver:  r,
+		namespace: namespace,
+	}
+}
+
+func (r *resolver) Resolve(ctx context.Context, namespace string, id, key *string) (*feature.Feature, error) {
+	hasID := id != nil && *id != ""
+	hasKey := key != nil && *key != ""
+
+	if !hasID && !hasKey {
+		return nil, errors.New("feature id or key is required")
+	}
+
+	batch := make([]string, 0, 2)
+
+	if hasID {
+		batch = append(batch, *id)
+	}
+
+	if hasKey {
+		batch = append(batch, *key)
+	}
+
+	features, err := r.BatchResolve(ctx, namespace, batch...)
+	if err != nil {
+		return nil, fmt.Errorf("failed to fetch feature: %w", err)
+	}
+
+	var f *feature.Feature
+
+	if hasID {
+		f = features[*id]
+
+		if f == nil {
+			return nil, models.NewGenericNotFoundError(fmt.Errorf("feature [feature.id=%s]", lo.FromPtr(id)))
+		}
+
+		if f.ID != *id {
+			return nil, models.NewGenericConflictError(fmt.Errorf("feature [feature.id=%s feature.key=%s]", lo.FromPtr(id), lo.FromPtr(key)))
+		}
+	}
+
+	if hasKey {
+		if f == nil {
+			f = features[*key]
+		}
+
+		if f == nil {
+			return nil, models.NewGenericNotFoundError(fmt.Errorf("feature [feature.key=%s]", lo.FromPtr(key)))
+		}
+
+		if features[*key] == nil {
+			return nil, models.NewGenericNotFoundError(fmt.Errorf("feature [feature.key=%s]", lo.FromPtr(key)))
+		}
+
+		if f.Key != *key {
+			return nil, models.NewGenericConflictError(fmt.Errorf("feature [feature.id=%s feature.key=%s]", lo.FromPtr(id), lo.FromPtr(key)))
+		}
+	}
+
+	return f, nil
+}
+
+func (r *resolver) BatchResolve(ctx context.Context, namespace string, idsOrKeys ...string) (map[string]*feature.Feature, error) {
+	if namespace == "" {
+		return nil, errors.New("namespace is not set")
+	}
+
+	if len(idsOrKeys) == 0 {
+		return nil, nil
+	}
+
+	features, err := pagination.CollectAll(ctx, pagination.NewPaginator(func(ctx context.Context, page pagination.Page) (pagination.Result[feature.Feature], error) {
+		return r.service.ListFeatures(ctx, feature.ListFeaturesParams{
+			IDsOrKeys:       idsOrKeys,
+			Namespace:       namespace,
+			IncludeArchived: false,
+			Page:            page,
+		})
+	}), min(len(idsOrKeys), 100))
+	if err != nil {
+		return nil, fmt.Errorf("failed to fetch features: %w", err)
+	}
+
+	result := lo.SliceToMap(idsOrKeys, func(item string) (string, *feature.Feature) {
+		return item, nil
+	})
+
+	for idx := range features {
+		f := features[idx]
+
+		if _, ok := result[f.ID]; ok {
+			result[f.ID] = &f
+		}
+
+		if _, ok := result[f.Key]; ok {
+			result[f.Key] = &f
+		}
+	}
+
+	return result, nil
+}

openmeter/productcatalog/featureresolver/resolver_test.go

@@ -0,0 +1,188 @@
+package featureresolver_test
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/samber/lo"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/featureresolver"
+	pctestutils "github.com/openmeterio/openmeter/openmeter/productcatalog/testutils"
+	"github.com/openmeterio/openmeter/pkg/models"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+)
+
+func Test_NamespacedFeatureResolver(t *testing.T) {
+	// Setup test environment
+	env := pctestutils.NewTestEnv(t)
+	t.Cleanup(func() {
+		env.Close(t)
+	})
+
+	// Run database migrations
+
+	// Get new namespace ID
+	namespace := pctestutils.NewTestNamespace(t)
+
+	// Setup meter repository
+	err := env.Meter.ReplaceMeters(t.Context(), pctestutils.NewTestMeters(t, namespace))
+	require.NoError(t, err, "replacing meters must not fail")
+
+	result, err := env.Meter.ListMeters(t.Context(), meter.ListMetersParams{
+		Page: pagination.Page{
+			PageSize:   1000,
+			PageNumber: 1,
+		},
+		Namespace: namespace,
+	})
+	require.NoErrorf(t, err, "listing meters must not fail")
+
+	meters := result.Items
+	require.NotEmptyf(t, meters, "list of Meters must not be empty")
+
+	// Set a feature for each meter
+	features := make([]feature.Feature, 0, len(meters))
+	for _, m := range meters {
+		input := pctestutils.NewTestFeatureFromMeter(t, &m)
+
+		feat, err := env.Feature.CreateFeature(t.Context(), input)
+		require.NoErrorf(t, err, "creating feature must not fail")
+		require.NotNil(t, feat, "feature must not be empty")
+
+		features = append(features, feat)
+	}
+	require.NotEmptyf(t, features, "list of Features must not be empty")
+	require.Lenf(t, features, len(meters), "list of Features must have the same length as the list of Meters")
+
+	resolver, err := featureresolver.New(env.Feature)
+	require.NoError(t, err, "creating feature resolver must not fail")
+
+	namespacedResolver := resolver.WithNamespace(namespace)
+
+	t.Run("Resolve", func(t *testing.T) {
+		tests := []struct {
+			name       string
+			featureID  *string
+			featureKey *string
+
+			expectedError error
+		}{
+			{
+				name:          "nil",
+				featureID:     nil,
+				featureKey:    nil,
+				expectedError: errors.New("feature id or key is required"),
+			},
+			{
+				name:          "by id",
+				featureID:     &features[0].ID,
+				featureKey:    nil,
+				expectedError: nil,
+			},
+			{
+				name:          "by key",
+				featureID:     nil,
+				featureKey:    &features[0].Key,
+				expectedError: nil,
+			},
+			{
+				name:          "by both id and key",
+				featureID:     &features[0].ID,
+				featureKey:    &features[0].Key,
+				expectedError: nil,
+			},
+			{
+				name:          "by non-existing id",
+				featureID:     lo.ToPtr("abracadabraId"),
+				featureKey:    nil,
+				expectedError: new(models.GenericNotFoundError),
+			},
+			{
+				name:          "by non-existing key",
+				featureID:     nil,
+				featureKey:    lo.ToPtr("abracadabraKey"),
+				expectedError: new(models.GenericNotFoundError),
+			},
+			{
+				name:          "by non-existing id and key",
+				featureID:     lo.ToPtr("abracadabraId"),
+				featureKey:    lo.ToPtr("abracadabraKey"),
+				expectedError: new(models.GenericNotFoundError),
+			},
+			{
+				name:          "mismatched id and key",
+				featureID:     &features[0].ID,
+				featureKey:    &features[1].Key,
+				expectedError: new(models.GenericConflictError),
+			},
+			{
+				name:          "id is actually a key",
+				featureID:     &features[0].Key,
+				featureKey:    nil,
+				expectedError: new(models.GenericConflictError),
+			},
+			{
+				name:          "key is actually an id",
+				featureID:     nil,
+				featureKey:    &features[0].ID,
+				expectedError: new(models.GenericConflictError),
+			},
+		}
+
+		for _, test := range tests {
+			t.Run(test.name, func(t *testing.T) {
+				var f *feature.Feature
+
+				f, err = namespacedResolver.Resolve(t.Context(), test.featureID, test.featureKey)
+				if test.expectedError != nil {
+					assert.ErrorAsf(t, err, &test.expectedError, "expected error %v", test.expectedError)
+				} else {
+					require.NoErrorf(t, err, "expected no error: %v", err)
+
+					if test.featureID != nil {
+						assert.Equalf(t, *test.featureID, f.ID, "resolved feature id must be equal to the one we set")
+					}
+
+					if test.featureKey != nil {
+						assert.Equalf(t, *test.featureKey, f.Key, "resolved feature key must be equal to the one we set")
+					}
+				}
+			})
+		}
+	})
+
+	t.Run("BatchResolve", func(t *testing.T) {
+		testBatch := map[string]*feature.Feature{
+			features[0].ID:  &features[0],
+			features[0].Key: &features[0],
+			features[1].ID:  &features[1],
+			features[1].Key: &features[1],
+			features[2].ID:  &features[2],
+			features[2].Key: &features[2],
+			"abracadabra":   nil,
+		}
+
+		idOrKeys := lo.MapToSlice(testBatch, func(key string, _ *feature.Feature) string {
+			return key
+		})
+
+		var resolved map[string]*feature.Feature
+
+		resolved, err = namespacedResolver.BatchResolve(t.Context(), idOrKeys...)
+		require.NoErrorf(t, err, "expected no error: %v", err)
+
+		for k, f := range testBatch {
+			if f != nil {
+				assert.NotNilf(t, resolved[k], "resolved feature must not be nil")
+				assert.Equalf(t, f.ID, resolved[k].ID, "resolved feature id must be equal to the one we set")
+				assert.Equalf(t, f.Key, resolved[k].Key, "resolved feature key must be equal to the one we set")
+			} else {
+				assert.Nilf(t, resolved[k], "resolved feature must be nil")
+			}
+		}
+	})
+}

openmeter/productcatalog/http/errors.go

@@ -0,0 +1,53 @@
+package http
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport/encoder"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+func ValidationErrorEncoder(kind ResourceKind) encoder.ErrorEncoder {
+	return func(ctx context.Context, err error, w http.ResponseWriter, r *http.Request) bool {
+		issues, err := models.AsValidationIssues(err)
+
+		if err == nil && len(issues) > 0 {
+			err = validationError{
+				kind:   kind,
+				issues: issues,
+			}
+
+			return commonhttp.HandleErrorIfTypeMatches[validationError](ctx, http.StatusBadRequest, err, w, validationErrorToExtensions)
+		}
+
+		return false
+	}
+}
+
+var _ error = (*validationError)(nil)
+
+type validationError struct {
+	kind   ResourceKind
+	issues models.ValidationIssues
+}
+
+func (e validationError) Error() string {
+	return "invalid " + string(e.kind)
+}
+
+func validationErrorToExtensions(err validationError) map[string]interface{} {
+	if len(err.issues) == 0 {
+		return nil
+	}
+
+	var issues []map[string]interface{}
+	for _, issue := range err.issues {
+		issues = append(issues, issue.AsErrorExtension())
+	}
+
+	return map[string]interface{}{
+		"validationErrors": issues,
+	}
+}