Upload folder using huggingface_hub (part 4)

api/v3/handlers/customers/credits/list_transactions.go

@@ -0,0 +1,157 @@
+package customerscredits
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+
+	"github.com/oapi-codegen/nullable"
+	"github.com/samber/lo"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/openmeter/customer"
+	"github.com/openmeterio/openmeter/openmeter/ledger/customerbalance"
+	"github.com/openmeterio/openmeter/pkg/currencyx"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type (
+	ListCreditTransactionsRequest  = customerbalance.ListCreditTransactionsInput
+	ListCreditTransactionsResponse = api.CreditTransactionPaginatedResponse
+	ListCreditTransactionsParams   struct {
+		CustomerID api.ULID
+		Params     api.ListCreditTransactionsParams
+	}
+	ListCreditTransactionsHandler httptransport.HandlerWithArgs[ListCreditTransactionsRequest, ListCreditTransactionsResponse, ListCreditTransactionsParams]
+)
+
+func (h *handler) ListCreditTransactions() ListCreditTransactionsHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, args ListCreditTransactionsParams) (ListCreditTransactionsRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return ListCreditTransactionsRequest{}, err
+			}
+
+			size := 20
+			if args.Params.Page != nil {
+				size = lo.FromPtrOr(args.Params.Page.Size, 20)
+			}
+
+			if size < 1 {
+				err := fmt.Errorf("must be greater than 0")
+				return ListCreditTransactionsRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+					{
+						Field:  "page.size",
+						Reason: "must be greater than 0",
+						Source: apierrors.InvalidParamSourceQuery,
+					},
+				})
+			}
+
+			req := customerbalance.ListCreditTransactionsInput{
+				CustomerID: customer.CustomerID{
+					Namespace: ns,
+					ID:        args.CustomerID,
+				},
+				Limit: size,
+			}
+
+			if args.Params.Page != nil {
+				if args.Params.Page.After != nil {
+					after, err := decodeBillingCreditTransactionCursor(*args.Params.Page.After, ns)
+					if err != nil {
+						return ListCreditTransactionsRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+							{
+								Field:  "page.after",
+								Reason: err.Error(),
+								Source: apierrors.InvalidParamSourceQuery,
+							},
+						})
+					}
+
+					req.After = after
+				}
+
+				if args.Params.Page.Before != nil {
+					before, err := decodeBillingCreditTransactionCursor(*args.Params.Page.Before, ns)
+					if err != nil {
+						return ListCreditTransactionsRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+							{
+								Field:  "page.before",
+								Reason: err.Error(),
+								Source: apierrors.InvalidParamSourceQuery,
+							},
+						})
+					}
+
+					req.Before = before
+				}
+			}
+
+			if args.Params.Filter != nil {
+				req.Type = fromAPIBillingCreditTransactionType(args.Params.Filter.Type)
+
+				if args.Params.Filter.Currency != nil {
+					currency := currencyx.Code(*args.Params.Filter.Currency)
+					req.Currency = &currency
+				}
+
+				featureFilter, err := fromAPICustomerCreditFeatureFilter(args.Params.Filter.FeatureKey)
+				if err != nil {
+					return ListCreditTransactionsRequest{}, newFeatureKeyFilterBadRequest(ctx, err)
+				}
+
+				req.FeatureFilter = featureFilter
+			}
+
+			return req, nil
+		},
+		func(ctx context.Context, request ListCreditTransactionsRequest) (ListCreditTransactionsResponse, error) {
+			result, err := h.balanceFacade.ListCreditTransactions(ctx, request)
+			if err != nil {
+				return ListCreditTransactionsResponse{}, fmt.Errorf("list credit transactions: %w", err)
+			}
+
+			// We intentionally expose opaque cursor tokens instead of URI links.
+			// This endpoint reuses the shared cursor metadata schema, but still emits
+			// opaque token values rather than fully qualified URLs.
+			meta := api.CursorMeta{
+				Page: api.CursorMetaPage{
+					Next:     nullable.NewNullNullable[string](),
+					Previous: nullable.NewNullNullable[string](),
+					Size:     float32(request.Limit),
+				},
+			}
+
+			if result.NextCursor != nil {
+				next, err := encodeBillingCreditTransactionCursor(*result.NextCursor)
+				if err != nil {
+					return ListCreditTransactionsResponse{}, fmt.Errorf("encode next cursor: %w", err)
+				}
+				meta.Page.Next = nullable.NewNullableWithValue(next)
+			}
+
+			if result.PreviousCursor != nil {
+				previous, err := encodeBillingCreditTransactionCursor(*result.PreviousCursor)
+				if err != nil {
+					return ListCreditTransactionsResponse{}, fmt.Errorf("encode previous cursor: %w", err)
+				}
+				meta.Page.Previous = nullable.NewNullableWithValue(previous)
+			}
+
+			return api.CreditTransactionPaginatedResponse{
+				Data: toAPIBillingCreditTransactions(result.Items),
+				Meta: meta,
+			}, nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[ListCreditTransactionsResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("list-credit-transactions"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/customers/credits/list_transactions_test.go

@@ -0,0 +1,117 @@
+package customerscredits
+
+import (
+	"testing"
+	"time"
+
+	"github.com/alpacahq/alpacadecimal"
+	"github.com/stretchr/testify/require"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/openmeter/ledger"
+	"github.com/openmeterio/openmeter/openmeter/ledger/customerbalance"
+	"github.com/openmeterio/openmeter/pkg/currencyx"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+func TestFromAPIBillingCreditTransactionType_Funded(t *testing.T) {
+	filter := api.BillingCreditTransactionTypeFunded
+
+	txType := fromAPIBillingCreditTransactionType(&filter)
+
+	require.NotNil(t, txType)
+	require.Equal(t, customerbalance.CreditTransactionTypeFunded, *txType)
+}
+
+func TestFromAPIBillingCreditTransactionType_Expired(t *testing.T) {
+	filter := api.BillingCreditTransactionTypeExpired
+
+	txType := fromAPIBillingCreditTransactionType(&filter)
+
+	require.NotNil(t, txType)
+	require.Equal(t, customerbalance.CreditTransactionTypeExpired, *txType)
+}
+
+func TestToAPIBillingCreditTransaction(t *testing.T) {
+	createdAt := time.Date(2026, 4, 10, 9, 0, 0, 0, time.UTC)
+	bookedAt := createdAt.Add(time.Second)
+	description := "Welcome credits"
+
+	tx := toAPIBillingCreditTransaction(customerbalance.CreditTransaction{
+		ID: models.NamespacedID{
+			Namespace: "ns",
+			ID:        "tx-1",
+		},
+		CreatedAt: createdAt,
+		BookedAt:  bookedAt,
+		Type:      customerbalance.CreditTransactionTypeConsumed,
+		Currency:  currencyx.Code("USD"),
+		Amount:    alpacadecimal.NewFromInt(-10),
+		Balance: customerbalance.CreditTransactionBalance{
+			Before: alpacadecimal.NewFromInt(52),
+			After:  alpacadecimal.NewFromInt(42),
+		},
+		Name:        "credit_transaction",
+		Description: &description,
+		Annotations: models.Annotations{
+			ledger.AnnotationChargeID: "charge-1",
+		},
+	})
+
+	require.Equal(t, api.ULID("tx-1"), tx.Id)
+	require.Equal(t, api.BillingCreditTransactionTypeConsumed, tx.Type)
+	require.Equal(t, api.BillingCurrencyCode("USD"), tx.Currency)
+	require.Equal(t, api.Numeric("-10"), tx.Amount)
+	require.Equal(t, api.Numeric("52"), tx.AvailableBalance.Before)
+	require.Equal(t, api.Numeric("42"), tx.AvailableBalance.After)
+	require.NotNil(t, tx.Description)
+	require.Equal(t, description, *tx.Description)
+	require.NotNil(t, tx.Labels)
+	require.Equal(t, "charge-1", (*tx.Labels)["charge_id"])
+}
+
+func TestToAPIBillingCreditTransaction_Expired(t *testing.T) {
+	tx := toAPIBillingCreditTransaction(customerbalance.CreditTransaction{
+		ID: models.NamespacedID{
+			Namespace: "ns",
+			ID:        "tx-1",
+		},
+		CreatedAt: time.Date(2026, 4, 10, 9, 0, 0, 0, time.UTC),
+		BookedAt:  time.Date(2026, 4, 11, 9, 0, 0, 0, time.UTC),
+		Type:      customerbalance.CreditTransactionTypeExpired,
+		Currency:  currencyx.Code("USD"),
+		Amount:    alpacadecimal.NewFromInt(-4),
+	})
+
+	require.Equal(t, api.BillingCreditTransactionTypeExpired, tx.Type)
+}
+
+func TestCreditTransactionCursorConversion(t *testing.T) {
+	bookedAt := time.Date(2026, 4, 10, 10, 0, 0, 0, time.UTC)
+	createdAt := bookedAt.Add(-time.Second)
+	namespace := "ns"
+
+	ledgerCursor := ledger.TransactionCursor{
+		BookedAt:  bookedAt,
+		CreatedAt: createdAt,
+		ID: models.NamespacedID{
+			Namespace: namespace,
+			ID:        "01J7JABCDXYZ1234567890ABCD",
+		},
+	}
+
+	encoded, err := encodeBillingCreditTransactionCursor(ledgerCursor)
+	require.NoError(t, err)
+
+	decoded, err := decodeBillingCreditTransactionCursor(encoded, namespace)
+	require.NoError(t, err)
+	require.Equal(t, bookedAt, decoded.BookedAt)
+	require.Equal(t, createdAt, decoded.CreatedAt)
+	require.Equal(t, namespace, decoded.ID.Namespace)
+	require.Equal(t, ledgerCursor.ID.ID, decoded.ID.ID)
+}
+
+func TestCreditTransactionCursorConversion_InvalidCursor(t *testing.T) {
+	_, err := decodeBillingCreditTransactionCursor("not-base64", "ns")
+	require.Error(t, err)
+}

api/v3/handlers/customers/credits/void_grant.go

@@ -0,0 +1,55 @@
+package customerscredits
+
+import (
+	"context"
+	"net/http"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/api/v3/request"
+	"github.com/openmeterio/openmeter/openmeter/billing/creditgrant"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type (
+	VoidCreditGrantRequest  = creditgrant.VoidInput
+	VoidCreditGrantResponse = api.BillingCreditGrant
+	VoidCreditGrantParams   struct {
+		CustomerID    api.ULID
+		CreditGrantID api.ULID
+	}
+	VoidCreditGrantHandler = httptransport.HandlerWithArgs[VoidCreditGrantRequest, VoidCreditGrantResponse, VoidCreditGrantParams]
+)
+
+func (h *handler) VoidCreditGrant() VoidCreditGrantHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, args VoidCreditGrantParams) (VoidCreditGrantRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return VoidCreditGrantRequest{}, err
+			}
+
+			var body api.VoidCreditGrantRequest
+			if err := request.ParseOptionalBody(r, &body); err != nil {
+				return VoidCreditGrantRequest{}, err
+			}
+
+			return fromAPIVoidCreditGrantRequest(ns, args.CustomerID, args.CreditGrantID, body)
+		},
+		func(ctx context.Context, request VoidCreditGrantRequest) (VoidCreditGrantResponse, error) {
+			grant, err := h.creditGrantService.Void(ctx, request)
+			if err != nil {
+				return VoidCreditGrantResponse{}, err
+			}
+
+			return toAPIBillingCreditGrant(grant)
+		},
+		commonhttp.JSONResponseEncoderWithStatus[VoidCreditGrantResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("void-credit-grant"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/customers/credits/void_grant_test.go

@@ -0,0 +1,71 @@
+package customerscredits
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/openmeter/billing/creditgrant"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+func TestConvertAPIVoidCreditGrantRequestDefaultsPaymentAdjustment(t *testing.T) {
+	req, err := fromAPIVoidCreditGrantRequest(
+		"ns",
+		"cust-1",
+		"grant-1",
+		api.VoidCreditGrantRequest{},
+	)
+
+	require.NoError(t, err)
+	require.Equal(t, "ns", req.Namespace)
+	require.Equal(t, "cust-1", req.CustomerID)
+	require.Equal(t, "grant-1", req.ChargeID)
+	require.Equal(t, creditgrant.VoidPaymentAdjustmentNone, req.PaymentAdjustment)
+}
+
+func TestConvertAPIVoidCreditGrantRequestAcceptsNonePaymentAdjustment(t *testing.T) {
+	adjustment := api.BillingCreditGrantVoidPaymentAdjustmentNone
+
+	req, err := fromAPIVoidCreditGrantRequest(
+		"ns",
+		"cust-1",
+		"grant-1",
+		api.VoidCreditGrantRequest{
+			PaymentAdjustment: &adjustment,
+		},
+	)
+
+	require.NoError(t, err)
+	require.Equal(t, creditgrant.VoidPaymentAdjustmentNone, req.PaymentAdjustment)
+}
+
+func TestConvertAPIVoidCreditGrantRequestRejectsUnsupportedPaymentAdjustment(t *testing.T) {
+	adjustment := api.BillingCreditGrantVoidPaymentAdjustment("external")
+
+	_, err := fromAPIVoidCreditGrantRequest(
+		"ns",
+		"cust-1",
+		"grant-1",
+		api.VoidCreditGrantRequest{
+			PaymentAdjustment: &adjustment,
+		},
+	)
+
+	require.Error(t, err)
+	issues, convErr := models.AsValidationIssues(err)
+	require.NoError(t, convErr)
+	require.Len(t, issues, 1)
+	require.ErrorContains(t, err, "unsupported credit grant void payment adjustment")
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/v3/customers/cust-1/credits/grants/grant-1/void", nil)
+	handled := apierrors.GenericErrorEncoder()(t.Context(), err, rec, req)
+
+	require.True(t, handled)
+	require.Equal(t, http.StatusBadRequest, rec.Code)
+}

api/v3/handlers/customers/delete.go

@@ -0,0 +1,55 @@
+package customers
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	customer "github.com/openmeterio/openmeter/openmeter/customer"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type (
+	DeleteCustomerRequest struct {
+		Namespace  string
+		CustomerID string
+	}
+	DeleteCustomerResponse = interface{}
+	DeleteCustomerParams   = string
+	DeleteCustomerHandler  httptransport.HandlerWithArgs[DeleteCustomerRequest, DeleteCustomerResponse, DeleteCustomerParams]
+)
+
+// DeleteCustomer returns a handler for deleting a customer.
+func (h *handler) DeleteCustomer() DeleteCustomerHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, customerID DeleteCustomerParams) (DeleteCustomerRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return DeleteCustomerRequest{}, err
+			}
+
+			return DeleteCustomerRequest{
+				Namespace:  ns,
+				CustomerID: customerID,
+			}, nil
+		},
+		func(ctx context.Context, request DeleteCustomerRequest) (DeleteCustomerResponse, error) {
+			err := h.service.DeleteCustomer(ctx, customer.DeleteCustomerInput{
+				Namespace: request.Namespace,
+				ID:        request.CustomerID,
+			})
+			if err != nil {
+				return nil, err
+			}
+
+			return nil, nil
+		},
+		commonhttp.EmptyResponseEncoder[DeleteCustomerResponse](http.StatusNoContent),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("delete-customer"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/customers/entitlementaccess/handler.go

@@ -0,0 +1,34 @@
+package customersentitlement
+
+import (
+	"context"
+
+	"github.com/openmeterio/openmeter/openmeter/customer"
+	"github.com/openmeterio/openmeter/openmeter/entitlement"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type Handler interface {
+	ListCustomerEntitlementAccess() ListCustomerEntitlementAccessHandler
+}
+
+type handler struct {
+	resolveNamespace   func(ctx context.Context) (string, error)
+	customerService    customer.Service
+	entitlementService entitlement.Service
+	options            []httptransport.HandlerOption
+}
+
+func New(
+	resolveNamespace func(ctx context.Context) (string, error),
+	customerService customer.Service,
+	entitlementService entitlement.Service,
+	options ...httptransport.HandlerOption,
+) Handler {
+	return &handler{
+		resolveNamespace:   resolveNamespace,
+		customerService:    customerService,
+		entitlementService: entitlementService,
+		options:            options,
+	}
+}

api/v3/handlers/customers/entitlementaccess/list.go

@@ -0,0 +1,97 @@
+package customersentitlement
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"sort"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/openmeter/customer"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type (
+	CustomerID                            = string
+	ListCustomerEntitlementAccessResponse = api.ListCustomerEntitlementAccessResponseData
+	ListCustomerEntitlementAccessHandler  httptransport.HandlerWithArgs[ListCustomerEntitlementAccessRequest, ListCustomerEntitlementAccessResponse, CustomerID]
+)
+
+type ListCustomerEntitlementAccessRequest struct {
+	CustomerID customer.CustomerID
+}
+
+func (h *handler) ListCustomerEntitlementAccess() ListCustomerEntitlementAccessHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, customerID CustomerID) (ListCustomerEntitlementAccessRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return ListCustomerEntitlementAccessRequest{}, err
+			}
+
+			req := ListCustomerEntitlementAccessRequest{
+				CustomerID: customer.CustomerID{
+					Namespace: ns,
+					ID:        customerID,
+				},
+			}
+
+			return req, nil
+		},
+		func(ctx context.Context, request ListCustomerEntitlementAccessRequest) (ListCustomerEntitlementAccessResponse, error) {
+			// Get the customer
+			cus, err := h.customerService.GetCustomer(ctx, customer.GetCustomerInput{
+				CustomerID: &request.CustomerID,
+			})
+			if err != nil {
+				return ListCustomerEntitlementAccessResponse{}, err
+			}
+
+			if cus != nil && cus.IsDeleted() {
+				return ListCustomerEntitlementAccessResponse{},
+					apierrors.NewPreconditionFailedError(ctx,
+						fmt.Sprintf("customer is deleted [namespace=%s customer.id=%s]", cus.Namespace, cus.ID),
+					)
+			}
+
+			// Get the access
+			access, err := h.entitlementService.GetAccess(ctx, cus.Namespace, cus.ID)
+			if err != nil {
+				return ListCustomerEntitlementAccessResponse{}, err
+			}
+
+			// Convert the access to the API response
+			items := make([]api.BillingEntitlementAccessResult, 0, len(access.Entitlements))
+			for featureKey, entitlement := range access.Entitlements {
+				found, item, err := mapEntitlementValueToAPI(featureKey, entitlement.Value)
+				if err != nil {
+					return ListCustomerEntitlementAccessResponse{}, err
+				}
+
+				if !found {
+					continue
+				}
+
+				items = append(items, item)
+			}
+
+			// Sort the items by feature key
+			sort.Slice(items, func(i, j int) bool {
+				return items[i].FeatureKey < items[j].FeatureKey
+			})
+
+			// Return the response
+			return ListCustomerEntitlementAccessResponse{
+				Data: items,
+			}, nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[ListCustomerEntitlementAccessResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("list-customer-entitlement-access"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/customers/entitlementaccess/mapping.go

@@ -0,0 +1,46 @@
+package customersentitlement
+
+import (
+	"errors"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/openmeter/entitlement"
+	booleanentitlement "github.com/openmeterio/openmeter/openmeter/entitlement/boolean"
+	meteredentitlement "github.com/openmeterio/openmeter/openmeter/entitlement/metered"
+	staticentitlement "github.com/openmeterio/openmeter/openmeter/entitlement/static"
+)
+
+// mapEntitlementValueToAPI maps an entitlement value to an API entitlement access result.
+func mapEntitlementValueToAPI(featureKey string, entitlementValue entitlement.EntitlementValue) (bool, api.BillingEntitlementAccessResult, error) {
+	switch ent := entitlementValue.(type) {
+	case *meteredentitlement.MeteredEntitlementValue:
+		return true, api.BillingEntitlementAccessResult{
+			FeatureKey: featureKey,
+			Type:       api.BillingEntitlementTypeMetered,
+			HasAccess:  ent.HasAccess(),
+		}, nil
+	case *staticentitlement.StaticEntitlementValue:
+		accessResult := api.BillingEntitlementAccessResult{
+			FeatureKey: featureKey,
+			Type:       api.BillingEntitlementTypeStatic,
+			HasAccess:  ent.HasAccess(),
+			Config:     &ent.Config,
+		}
+
+		return true, accessResult, nil
+	case *booleanentitlement.BooleanEntitlementValue:
+		return true, api.BillingEntitlementAccessResult{
+			FeatureKey: featureKey,
+			Type:       api.BillingEntitlementTypeBoolean,
+			HasAccess:  ent.HasAccess(),
+		}, nil
+
+	case *entitlement.NoAccessValue:
+		// FIXME(pmarton): do we need to handle no access value?
+		// According to comments this only happens when the entitlement is not active
+		// This is the reason why we return a bool and not an error
+		return false, api.BillingEntitlementAccessResult{}, nil
+	default:
+		return true, api.BillingEntitlementAccessResult{}, errors.New("unknown entitlement type")
+	}
+}

api/v3/handlers/customers/get.go

@@ -0,0 +1,53 @@
+package customers
+
+import (
+	"context"
+	"net/http"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/openmeter/customer"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type (
+	GetCustomerRequest  = customer.GetCustomerInput
+	GetCustomerResponse = api.BillingCustomer
+	GetCustomerParams   = string
+	GetCustomerHandler  httptransport.HandlerWithArgs[GetCustomerRequest, GetCustomerResponse, GetCustomerParams]
+)
+
+// GetCustomer returns a handler for getting a customer.
+func (h *handler) GetCustomer() GetCustomerHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, customerID GetCustomerParams) (GetCustomerRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return GetCustomerRequest{}, err
+			}
+
+			return GetCustomerRequest{
+				CustomerID: &customer.CustomerID{
+					Namespace: ns,
+					ID:        customerID,
+				},
+			}, nil
+		},
+		func(ctx context.Context, request GetCustomerRequest) (GetCustomerResponse, error) {
+			// Get the customer
+			cus, err := h.service.GetCustomer(ctx, request)
+			if err != nil {
+				return GetCustomerResponse{}, err
+			}
+
+			return ToAPIBillingCustomer(*cus), nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[GetCustomerResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("get-customer"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/customers/handler.go

@@ -0,0 +1,34 @@
+package customers
+
+import (
+	"context"
+
+	"github.com/openmeterio/openmeter/openmeter/customer"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type Handler interface {
+	ListCustomers() ListCustomersHandler
+	CreateCustomer() CreateCustomerHandler
+	DeleteCustomer() DeleteCustomerHandler
+	GetCustomer() GetCustomerHandler
+	UpsertCustomer() UpsertCustomerHandler
+}
+
+type handler struct {
+	resolveNamespace func(ctx context.Context) (string, error)
+	service          customer.Service
+	options          []httptransport.HandlerOption
+}
+
+func New(
+	resolveNamespace func(ctx context.Context) (string, error),
+	service customer.Service,
+	options ...httptransport.HandlerOption,
+) Handler {
+	return &handler{
+		resolveNamespace: resolveNamespace,
+		service:          service,
+		options:          options,
+	}
+}

api/v3/handlers/customers/list.go

@@ -0,0 +1,154 @@
+package customers
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+
+	"github.com/samber/lo"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/api/v3/filters"
+	"github.com/openmeterio/openmeter/api/v3/request"
+	"github.com/openmeterio/openmeter/api/v3/response"
+	"github.com/openmeterio/openmeter/openmeter/customer"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+	"github.com/openmeterio/openmeter/pkg/sortx"
+)
+
+type (
+	ListCustomersRequest  = customer.ListCustomersInput
+	ListCustomersResponse = response.PagePaginationResponse[api.BillingCustomer]
+	ListCustomersParams   = api.ListCustomersParams
+	ListCustomersHandler  httptransport.HandlerWithArgs[ListCustomersRequest, ListCustomersResponse, ListCustomersParams]
+)
+
+func (h *handler) ListCustomers() ListCustomersHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, params ListCustomersParams) (ListCustomersRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return ListCustomersRequest{}, err
+			}
+
+			page := pagination.NewPage(1, 20)
+			if params.Page != nil {
+				page = pagination.NewPage(
+					lo.FromPtrOr(params.Page.Number, 1),
+					lo.FromPtrOr(params.Page.Size, 20),
+				)
+			}
+
+			if err := page.Validate(); err != nil {
+				return ListCustomersRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+					apierrors.InvalidParameter{
+						Field:  "page",
+						Reason: err.Error(),
+						Source: apierrors.InvalidParamSourceQuery,
+					},
+				})
+			}
+
+			var orderBy string
+			var order sortx.Order
+			if params.Sort != nil {
+				sort, err := request.ParseSortBy(*params.Sort)
+				if err != nil {
+					return ListCustomersRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						apierrors.InvalidParameter{
+							Field:  "sort",
+							Reason: err.Error(),
+							Source: apierrors.InvalidParamSourceQuery,
+						},
+					})
+				}
+				orderBy, err = FromAPICustomerSortField(ctx, sort.Field)
+				if err != nil {
+					return ListCustomersRequest{}, err
+				}
+				order = sort.Order.ToSortxOrder()
+			}
+
+			req := ListCustomersRequest{
+				Namespace: ns,
+				Page:      page,
+				OrderBy:   orderBy,
+				Order:     order,
+			}
+
+			if params.Filter != nil {
+				key, err := filters.FromAPIFilterString(params.Filter.Key)
+				if err != nil {
+					return ListCustomersRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[key]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.Key = key
+				name, err := filters.FromAPIFilterString(params.Filter.Name)
+				if err != nil {
+					return ListCustomersRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[name]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.Name = name
+				primaryEmail, err := filters.FromAPIFilterString(params.Filter.PrimaryEmail)
+				if err != nil {
+					return ListCustomersRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[primary_email]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.PrimaryEmail = primaryEmail
+				usageAttributionSubjectKey, err := filters.FromAPIFilterString(params.Filter.UsageAttributionSubjectKey)
+				if err != nil {
+					return ListCustomersRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[usage_attribution_subject_key]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.UsageAttributionSubjectKey = usageAttributionSubjectKey
+				planKey, err := filters.FromAPIFilterString(params.Filter.PlanKey)
+				if err != nil {
+					return ListCustomersRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[plan_key]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.PlanKey = planKey
+				billingProfileID, err := filters.FromAPIFilterULID(params.Filter.BillingProfileId)
+				if err != nil {
+					return ListCustomersRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[billing_profile_id]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.BillingProfileID = billingProfileID
+			}
+
+			return req, nil
+		},
+		func(ctx context.Context, request ListCustomersRequest) (ListCustomersResponse, error) {
+			resp, err := h.service.ListCustomers(ctx, request)
+			if err != nil {
+				return ListCustomersResponse{}, fmt.Errorf("failed to list customers: %w", err)
+			}
+
+			customers := lo.Map(resp.Items, func(item customer.Customer, _ int) api.BillingCustomer {
+				return ToAPIBillingCustomer(item)
+			})
+
+			r := response.NewPagePaginationResponse(customers, response.PageMetaPage{
+				Size:   request.Page.PageSize,
+				Number: request.Page.PageNumber,
+				Total:  lo.ToPtr(resp.TotalCount),
+			})
+
+			return r, nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[ListCustomersResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("list-customers"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/customers/upsert.go

@@ -0,0 +1,106 @@
+package customers
+
+import (
+	"context"
+	"errors"
+	"net/http"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/api/v3/request"
+	"github.com/openmeterio/openmeter/openmeter/customer"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type (
+	UpsertCustomerRequest struct {
+		Namespace      string
+		CustomerID     string
+		CustomerMutate customer.CustomerMutate
+	}
+	UpsertCustomerParams   = string
+	UpsertCustomerResponse = api.BillingCustomer
+	UpsertCustomerHandler  httptransport.HandlerWithArgs[UpsertCustomerRequest, UpsertCustomerResponse, UpsertCustomerParams]
+)
+
+// UpsertCustomer returns a handler for updating a customer.
+func (h *handler) UpsertCustomer() UpsertCustomerHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, customerID UpsertCustomerParams) (UpsertCustomerRequest, error) {
+			body := api.UpsertCustomerRequest{}
+			if err := request.ParseBody(r, &body); err != nil {
+				return UpsertCustomerRequest{}, err
+			}
+
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return UpsertCustomerRequest{}, err
+			}
+
+			customerMutate, err := FromAPIUpsertCustomerRequest(body)
+			if err != nil {
+				return UpsertCustomerRequest{}, err
+			}
+
+			req := UpsertCustomerRequest{
+				Namespace:  ns,
+				CustomerID: customerID,
+				// Key cannot be updated according to api.UpsertCustomerRequest.
+				// Therefore, at this point we don't have a key yet. It is ignored in this conversion.
+				CustomerMutate: customerMutate,
+			}
+
+			return req, nil
+		},
+		func(ctx context.Context, request UpsertCustomerRequest) (UpsertCustomerResponse, error) {
+			// FIXME: begin
+			//  Normally, we should avoid putting business logic in handlers, and we should avoid such extra
+			//  round-trips, since service.UpdateCustomer performs similar checks under the hood.
+			//  However, in v3 customer API, key cannot be updated, and service.UpdateCustomer will wipe the key in the
+			//  DB if it was nil in the input. Therefore, in order to avoid wiping the key, we need to get
+			//  and "backfill" it from the existing customer entity.
+			cus, err := h.service.GetCustomer(ctx, customer.GetCustomerInput{
+				CustomerID: &customer.CustomerID{
+					ID:        request.CustomerID,
+					Namespace: request.Namespace,
+				},
+			})
+			if err != nil {
+				return UpsertCustomerResponse{}, err
+			}
+
+			if cus.IsDeleted() {
+				return UpsertCustomerResponse{},
+					apierrors.NewGoneError(
+						ctx,
+						errors.New("customer is deleted"),
+					)
+			}
+
+			// Use the key from the just retrieved customer, as it is required by the UpdateCustomer service method.
+			request.CustomerMutate.Key = cus.Key
+			// FIXME: end
+
+			updatedCustomer, err := h.service.UpdateCustomer(ctx, customer.UpdateCustomerInput{
+				CustomerID:     cus.GetID(),
+				CustomerMutate: request.CustomerMutate,
+			})
+			if err != nil {
+				return UpsertCustomerResponse{}, err
+			}
+
+			if updatedCustomer == nil {
+				return UpsertCustomerResponse{}, errors.New("failed to update customer")
+			}
+
+			return ToAPIBillingCustomer(*updatedCustomer), nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[UpsertCustomerResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("upsert-customer"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/events/convert.go

@@ -0,0 +1,164 @@
+package events
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/oapi-codegen/nullable"
+	"github.com/samber/lo"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/api/v3/request"
+	"github.com/openmeterio/openmeter/openmeter/meterevent"
+	"github.com/openmeterio/openmeter/openmeter/streaming"
+	"github.com/openmeterio/openmeter/pkg/filter"
+	"github.com/openmeterio/openmeter/pkg/sortx"
+)
+
+const cloudEventsSpecVersion = "1.0"
+
+// toAPIMeteringIngestedEvent converts a meterevent.Event to its API wire form.
+func toAPIMeteringIngestedEvent(e meterevent.Event) (api.MeteringIngestedEvent, error) {
+	event := api.MeteringEvent{
+		Id:          e.ID,
+		Source:      e.Source,
+		Specversion: cloudEventsSpecVersion,
+		Subject:     e.Subject,
+		Type:        e.Type,
+		Time:        nullable.NewNullableWithValue[api.DateTime](e.Time),
+	}
+
+	if e.Data != "" {
+		var data map[string]any
+		if err := json.Unmarshal([]byte(e.Data), &data); err != nil {
+			return api.MeteringIngestedEvent{}, fmt.Errorf("parse event data as json: %w", err)
+		}
+		event.Data = nullable.NewNullableWithValue(data)
+		event.Datacontenttype = nullable.NewNullableWithValue[api.MeteringEventDatacontenttype](api.MeteringEventDatacontenttype("application/json"))
+	}
+
+	return api.MeteringIngestedEvent{
+		Event:            event,
+		Customer:         toAPICustomerReference(e.CustomerID),
+		IngestedAt:       e.IngestedAt,
+		StoredAt:         e.StoredAt,
+		ValidationErrors: toAPIMeteringIngestedEventValidationErrors(e.ValidationErrors),
+	}, nil
+}
+
+func toAPICustomerReference(id *string) *api.CustomerReference {
+	if id == nil || *id == "" {
+		return nil
+	}
+	return &api.CustomerReference{Id: *id}
+}
+
+func toAPIMeteringIngestedEventValidationErrors(errs []error) *[]api.MeteringIngestedEventValidationError {
+	if len(errs) == 0 {
+		return nil
+	}
+
+	result := lo.FilterMap(errs, func(err error, _ int) (api.MeteringIngestedEventValidationError, bool) {
+		if err == nil {
+			return api.MeteringIngestedEventValidationError{}, false
+		}
+
+		return api.MeteringIngestedEventValidationError{
+			Code:    "validation_error",
+			Message: err.Error(),
+		}, true
+	})
+
+	if len(result) == 0 {
+		return nil
+	}
+
+	return lo.ToPtr(result)
+}
+
+// fromAPICustomerIDFilter maps the v3 customer_id filter to the backend filter,
+// rejecting every operator that the underlying service cannot evaluate. Only
+// `eq` and `oeq` are supported because ListEventsV2Params requires a concrete
+// IN set.
+func fromAPICustomerIDFilter(ctx context.Context, f *api.ULIDFieldFilter) (*filter.FilterString, error) {
+	if f == nil {
+		return nil, nil
+	}
+
+	if f.Neq != nil {
+		err := errors.New("only eq and oeq operators are supported")
+		return nil, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+			{
+				Field:  "filter[customer_id]",
+				Reason: err.Error(),
+				Source: apierrors.InvalidParamSourceQuery,
+			},
+		})
+	}
+
+	var values []string
+	if f.Eq != nil {
+		values = append(values, *f.Eq)
+	}
+	if len(f.Oeq) > 0 {
+		values = append(values, f.Oeq...)
+	}
+
+	if len(values) == 0 {
+		return nil, nil
+	}
+
+	return &filter.FilterString{In: &values}, nil
+}
+
+func FromAPIEventSortField(ctx context.Context, field string) (streaming.EventSortField, error) {
+	switch field {
+	case "time":
+		return streaming.EventSortFieldTime, nil
+	case "ingested_at":
+		return streaming.EventSortFieldIngestedAt, nil
+	case "stored_at":
+		return streaming.EventSortFieldStoredAt, nil
+	default:
+		return "", apierrors.NewUnsupportedSortFieldError(
+			ctx, field, "time", "ingested_at", "stored_at",
+		)
+	}
+}
+
+// fromAPIEventSort resolves the public sort query into a backend sort field and direction.
+func fromAPIEventSort(ctx context.Context, sort *api.SortQuery) (streaming.EventSortField, sortx.Order, error) {
+	if lo.FromPtr(sort) == "" {
+		return "", "", nil
+	}
+
+	parsed, err := request.ParseSortBy(*sort)
+	if err != nil {
+		return "", "", apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+			{
+				Field:  "sort",
+				Reason: err.Error(),
+				Source: apierrors.InvalidParamSourceQuery,
+			},
+		})
+	}
+
+	field, err := FromAPIEventSortField(ctx, parsed.Field)
+	if err != nil {
+		return "", "", err
+	}
+
+	// If the caller did not supply an explicit asc/desc suffix, default to
+	// descending so `sort=time` behaves the same as omitting the parameter
+	// (most recent first).
+	order := parsed.Order.ToSortxOrder()
+	if len(strings.Fields(*sort)) == 1 {
+		order = sortx.OrderDesc
+	}
+
+	return field, order, nil
+}

api/v3/handlers/events/handler.go

@@ -0,0 +1,35 @@
+package events
+
+import (
+	"context"
+
+	"github.com/openmeterio/openmeter/openmeter/ingest"
+	"github.com/openmeterio/openmeter/openmeter/meterevent"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type Handler interface {
+	IngestEvents() IngestEventsHandler
+	ListMeteringEvents() ListMeteringEventsHandler
+}
+
+type handler struct {
+	resolveNamespace  func(ctx context.Context) (string, error)
+	service           ingest.Service
+	metereventService meterevent.Service
+	options           []httptransport.HandlerOption
+}
+
+func New(
+	resolveNamespace func(ctx context.Context) (string, error),
+	service ingest.Service,
+	metereventService meterevent.Service,
+	options ...httptransport.HandlerOption,
+) Handler {
+	return &handler{
+		resolveNamespace:  resolveNamespace,
+		service:           service,
+		metereventService: metereventService,
+		options:           options,
+	}
+}

api/v3/handlers/events/ingest.go

@@ -0,0 +1,106 @@
+package events
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"mime"
+	"net/http"
+
+	"github.com/cloudevents/sdk-go/v2/event"
+
+	"github.com/openmeterio/openmeter/api"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/openmeter/ingest"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type (
+	IngestEventsRequest  = ingest.IngestEventsRequest
+	IngestEventsResponse = *struct{}
+	IngestEventsHandler  httptransport.Handler[ingest.IngestEventsRequest, IngestEventsResponse]
+)
+
+func (h *handler) IngestEvents() IngestEventsHandler {
+	return httptransport.NewHandler(
+		func(ctx context.Context, r *http.Request) (ingest.IngestEventsRequest, error) {
+			req := ingest.IngestEventsRequest{}
+
+			namespace, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return req, err
+			}
+
+			req.Namespace = namespace
+
+			contentType, _, err := mime.ParseMediaType(r.Header.Get("Content-Type"))
+			if err != nil {
+				return req, apierrors.NewBadRequestError(ctx, err, nil)
+			}
+
+			switch contentType {
+			case "application/json":
+				var apiRequest api.IngestEventsBody
+
+				err := json.NewDecoder(r.Body).Decode(&apiRequest)
+				if err != nil {
+					return req, apierrors.NewBadRequestError(ctx, err, nil)
+				}
+
+				// Try to parse as a single event
+				e, err := apiRequest.AsEvent()
+				if err == nil {
+					req.Events = []event.Event{e}
+				} else {
+					// Try to parse as a batch of events
+					e, err := apiRequest.AsIngestEventsBody1()
+					if err == nil {
+						req.Events = e
+					}
+				}
+
+				// If we still don't have any events, return an error
+				if len(req.Events) == 0 {
+					return req, apierrors.NewBadRequestError(ctx, errors.New("no events found"), nil)
+				}
+			case "application/cloudevents+json":
+				var apiRequest api.IngestEventsApplicationCloudeventsPlusJSONRequestBody
+
+				err := json.NewDecoder(r.Body).Decode(&apiRequest)
+				if err != nil {
+					return req, apierrors.NewBadRequestError(ctx, err, nil)
+				}
+
+				req.Events = []event.Event{apiRequest}
+			case "application/cloudevents-batch+json":
+				var apiRequest api.IngestEventsApplicationCloudeventsBatchPlusJSONBody
+
+				err := json.NewDecoder(r.Body).Decode(&apiRequest)
+				if err != nil {
+					return req, apierrors.NewBadRequestError(ctx, err, nil)
+				}
+
+				req.Events = apiRequest
+			default:
+				return req, apierrors.NewBadRequestError(ctx, errors.New("invalid content type"), nil)
+			}
+
+			return req, nil
+		},
+		func(ctx context.Context, request ingest.IngestEventsRequest) (IngestEventsResponse, error) {
+			_, err := h.service.IngestEvents(ctx, request)
+			if err != nil {
+				return nil, err
+			}
+
+			return nil, nil
+		},
+		commonhttp.EmptyResponseEncoder[IngestEventsResponse](http.StatusAccepted),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("ingest-metering-events"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/events/list.go

@@ -0,0 +1,220 @@
+package events
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+
+	"github.com/samber/lo"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/api/v3/filters"
+	"github.com/openmeterio/openmeter/api/v3/response"
+	"github.com/openmeterio/openmeter/openmeter/meterevent"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+	pagination "github.com/openmeterio/openmeter/pkg/pagination/v2"
+	"github.com/openmeterio/openmeter/pkg/slicesx"
+)
+
+const defaultListMeteringEventsPageSize = 20
+
+type (
+	ListMeteringEventsRequest  = meterevent.ListEventsV2Params
+	ListMeteringEventsResponse = response.CursorPaginationResponse[api.MeteringIngestedEvent]
+	ListMeteringEventsParams   = api.ListMeteringEventsParams
+	ListMeteringEventsHandler  httptransport.HandlerWithArgs[ListMeteringEventsRequest, ListMeteringEventsResponse, ListMeteringEventsParams]
+)
+
+func (h *handler) ListMeteringEvents() ListMeteringEventsHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, params ListMeteringEventsParams) (ListMeteringEventsRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return ListMeteringEventsRequest{}, err
+			}
+
+			req := ListMeteringEventsRequest{
+				Namespace: ns,
+			}
+
+			pageSize := defaultListMeteringEventsPageSize
+			if params.Page != nil {
+				if params.Page.Before != nil {
+					return ListMeteringEventsRequest{}, apierrors.NewBadRequestError(ctx, errors.New("page[before] is not supported"), apierrors.InvalidParameters{
+						{
+							Field:  "page[before]",
+							Reason: "backward pagination is not supported",
+							Source: apierrors.InvalidParamSourceQuery,
+						},
+					})
+				}
+
+				if params.Page.After != nil {
+					cursor, err := pagination.DecodeCursor(*params.Page.After)
+					if err != nil {
+						return ListMeteringEventsRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+							{
+								Field:  "page[after]",
+								Reason: err.Error(),
+								Source: apierrors.InvalidParamSourceQuery,
+							},
+						})
+					}
+					req.Cursor = cursor
+				}
+
+				if params.Page.Size != nil {
+					pageSize = *params.Page.Size
+				}
+			}
+
+			if pageSize < 1 || pageSize > meterevent.MaximumLimit {
+				return ListMeteringEventsRequest{}, apierrors.NewBadRequestError(ctx, fmt.Errorf("page[size] must be between 1 and %d", meterevent.MaximumLimit), apierrors.InvalidParameters{
+					{
+						Field:  "page[size]",
+						Reason: fmt.Sprintf("must be between 1 and %d", meterevent.MaximumLimit),
+						Source: apierrors.InvalidParamSourceQuery,
+					},
+				})
+			}
+			req.Limit = lo.ToPtr(pageSize)
+
+			if params.Filter != nil {
+				if err := applyFilters(ctx, &req, params.Filter); err != nil {
+					return ListMeteringEventsRequest{}, err
+				}
+			}
+
+			sortBy, sortOrder, err := fromAPIEventSort(ctx, params.Sort)
+			if err != nil {
+				return ListMeteringEventsRequest{}, err
+			}
+			req.SortBy = sortBy
+			req.SortOrder = sortOrder
+
+			return req, nil
+		},
+		func(ctx context.Context, req ListMeteringEventsRequest) (ListMeteringEventsResponse, error) {
+			result, err := h.metereventService.ListEventsV2(ctx, req)
+			if err != nil {
+				return ListMeteringEventsResponse{}, err
+			}
+
+			items, err := slicesx.MapWithErr(result.Items, toAPIMeteringIngestedEvent)
+			if err != nil {
+				return ListMeteringEventsResponse{}, fmt.Errorf("convert events: %w", err)
+			}
+
+			pageSize := lo.FromPtrOr(req.Limit, defaultListMeteringEventsPageSize)
+			resp := response.NewCursorPaginationResponse(result.Items, pageSize)
+
+			return ListMeteringEventsResponse{
+				Data: items,
+				Meta: resp.Meta,
+			}, nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[ListMeteringEventsResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("list-metering-events"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}
+
+func applyFilters(ctx context.Context, req *ListMeteringEventsRequest, f *api.ListEventsParamsFilter) error {
+	id, err := filters.FromAPIFilterString(f.Id)
+	if err != nil {
+		return apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+			{
+				Field:  "filter[id]",
+				Reason: err.Error(),
+				Source: apierrors.InvalidParamSourceQuery,
+			},
+		})
+	}
+	req.ID = id
+
+	source, err := filters.FromAPIFilterString(f.Source)
+	if err != nil {
+		return apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+			{
+				Field:  "filter[source]",
+				Reason: err.Error(),
+				Source: apierrors.InvalidParamSourceQuery,
+			},
+		})
+	}
+	req.Source = source
+
+	subject, err := filters.FromAPIFilterString(f.Subject)
+	if err != nil {
+		return apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+			{
+				Field:  "filter[subject]",
+				Reason: err.Error(),
+				Source: apierrors.InvalidParamSourceQuery,
+			},
+		})
+	}
+	req.Subject = subject
+
+	typeFilter, err := filters.FromAPIFilterString(f.Type)
+	if err != nil {
+		return apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+			{
+				Field:  "filter[type]",
+				Reason: err.Error(),
+				Source: apierrors.InvalidParamSourceQuery,
+			},
+		})
+	}
+	req.Type = typeFilter
+
+	timeFilter, err := filters.FromAPIFilterDateTime(f.Time)
+	if err != nil {
+		return apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+			{
+				Field:  "filter[time]",
+				Reason: err.Error(),
+				Source: apierrors.InvalidParamSourceQuery,
+			},
+		})
+	}
+	req.Time = timeFilter
+
+	ingestedAt, err := filters.FromAPIFilterDateTime(f.IngestedAt)
+	if err != nil {
+		return apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+			{
+				Field:  "filter[ingested_at]",
+				Reason: err.Error(),
+				Source: apierrors.InvalidParamSourceQuery,
+			},
+		})
+	}
+	req.IngestedAt = ingestedAt
+
+	storedAt, err := filters.FromAPIFilterDateTime(f.StoredAt)
+	if err != nil {
+		return apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+			{
+				Field:  "filter[stored_at]",
+				Reason: err.Error(),
+				Source: apierrors.InvalidParamSourceQuery,
+			},
+		})
+	}
+	req.StoredAt = storedAt
+
+	customerID, err := fromAPICustomerIDFilter(ctx, f.CustomerId)
+	if err != nil {
+		return err
+	}
+	req.CustomerID = customerID
+
+	return nil
+}

api/v3/handlers/events/list_test.go

@@ -0,0 +1,110 @@
+package events
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/samber/lo"
+	"github.com/stretchr/testify/require"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/openmeter/streaming"
+	"github.com/openmeterio/openmeter/pkg/sortx"
+)
+
+func TestFromAPICustomerIDFilter(t *testing.T) {
+	ctx := t.Context()
+
+	t.Run("nil filter returns nil", func(t *testing.T) {
+		out, err := fromAPICustomerIDFilter(ctx, nil)
+		require.NoError(t, err)
+		require.Nil(t, out)
+	})
+
+	t.Run("eq maps to In with one element", func(t *testing.T) {
+		out, err := fromAPICustomerIDFilter(ctx, &api.ULIDFieldFilter{Eq: lo.ToPtr("01G65Z755AFWAKHE12NY0CQ9FH")})
+		require.NoError(t, err)
+		require.NotNil(t, out)
+		require.NotNil(t, out.In)
+		require.Equal(t, []string{"01G65Z755AFWAKHE12NY0CQ9FH"}, *out.In)
+	})
+
+	t.Run("oeq maps to In", func(t *testing.T) {
+		out, err := fromAPICustomerIDFilter(ctx, &api.ULIDFieldFilter{Oeq: []string{"a", "b"}})
+		require.NoError(t, err)
+		require.NotNil(t, out)
+		require.Equal(t, []string{"a", "b"}, *out.In)
+	})
+
+	t.Run("neq is rejected", func(t *testing.T) {
+		_, err := fromAPICustomerIDFilter(ctx, &api.ULIDFieldFilter{Neq: lo.ToPtr("x")})
+		require.Error(t, err)
+		assertBadRequestField(t, err, "filter[customer_id]")
+	})
+}
+
+func TestFromAPIEventSort(t *testing.T) {
+	ctx := t.Context()
+
+	t.Run("nil returns empty values", func(t *testing.T) {
+		field, order, err := fromAPIEventSort(ctx, nil)
+		require.NoError(t, err)
+		require.Equal(t, streaming.EventSortField(""), field)
+		require.Equal(t, sortx.Order(""), order)
+	})
+
+	t.Run("time defaults to desc when no suffix", func(t *testing.T) {
+		sort := api.SortQuery("time")
+		field, order, err := fromAPIEventSort(ctx, &sort)
+		require.NoError(t, err)
+		require.Equal(t, streaming.EventSortFieldTime, field)
+		require.Equal(t, sortx.OrderDesc, order)
+	})
+
+	t.Run("ingested_at desc", func(t *testing.T) {
+		sort := api.SortQuery("ingested_at desc")
+		field, order, err := fromAPIEventSort(ctx, &sort)
+		require.NoError(t, err)
+		require.Equal(t, streaming.EventSortFieldIngestedAt, field)
+		require.Equal(t, sortx.OrderDesc, order)
+	})
+
+	t.Run("stored_at defaults to desc when no suffix", func(t *testing.T) {
+		sort := api.SortQuery("stored_at")
+		field, order, err := fromAPIEventSort(ctx, &sort)
+		require.NoError(t, err)
+		require.Equal(t, streaming.EventSortFieldStoredAt, field)
+		require.Equal(t, sortx.OrderDesc, order)
+	})
+
+	t.Run("time asc suffix is honored", func(t *testing.T) {
+		sort := api.SortQuery("time asc")
+		field, order, err := fromAPIEventSort(ctx, &sort)
+		require.NoError(t, err)
+		require.Equal(t, streaming.EventSortFieldTime, field)
+		require.Equal(t, sortx.OrderAsc, order)
+	})
+
+	t.Run("unknown field is rejected", func(t *testing.T) {
+		sort := api.SortQuery("created_at")
+		_, _, err := fromAPIEventSort(ctx, &sort)
+		require.Error(t, err)
+		assertBadRequestField(t, err, "sort")
+	})
+
+	t.Run("malformed input is rejected", func(t *testing.T) {
+		sort := api.SortQuery("time bogus extra")
+		_, _, err := fromAPIEventSort(ctx, &sort)
+		require.Error(t, err)
+		assertBadRequestField(t, err, "sort")
+	})
+}
+
+func assertBadRequestField(t *testing.T, err error, field string) {
+	t.Helper()
+	var apiErr *apierrors.BaseAPIError
+	require.True(t, errors.As(err, &apiErr), "expected *apierrors.BaseAPIError, got %T", err)
+	require.Len(t, apiErr.InvalidParameters, 1)
+	require.Equal(t, field, apiErr.InvalidParameters[0].Field)
+}

api/v3/handlers/featurecost/convert.go

@@ -0,0 +1,69 @@
+package featurecost
+
+import (
+	"github.com/oapi-codegen/nullable"
+	"github.com/samber/lo"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/handlers/meters/query"
+	"github.com/openmeterio/openmeter/openmeter/cost"
+)
+
+// ToAPIFeatureCostQueryResult converts a domain CostQueryResult to the v3 API response.
+func ToAPIFeatureCostQueryResult(result *cost.CostQueryResult, body api.MeterQueryRequest) api.FeatureCostQueryResult {
+	if result == nil {
+		return api.FeatureCostQueryResult{
+			From: body.From,
+			To:   body.To,
+			Data: []api.FeatureCostQueryRow{},
+		}
+	}
+	return api.FeatureCostQueryResult{
+		From: body.From,
+		To:   body.To,
+		Data: lo.Map(result.Rows, func(row cost.CostQueryRow, _ int) api.FeatureCostQueryRow {
+			return toAPIFeatureCostQueryRow(row)
+		}),
+	}
+}
+
+func toAPIFeatureCostQueryRow(row cost.CostQueryRow) api.FeatureCostQueryRow {
+	dimensions := make(map[string]string)
+
+	if row.Subject != nil {
+		dimensions[query.DimensionSubject] = *row.Subject
+	}
+
+	if row.CustomerID != nil {
+		dimensions[query.DimensionCustomerID] = *row.CustomerID
+	}
+
+	for key, value := range row.GroupBy {
+		if key == query.DimensionSubject || key == query.DimensionCustomerID {
+			continue
+		}
+		if value != nil {
+			dimensions[key] = *value
+		}
+	}
+
+	apiRow := api.FeatureCostQueryRow{
+		Usage:      row.Usage.String(),
+		Currency:   api.CurrencyCode(row.Currency),
+		From:       row.WindowStart,
+		To:         row.WindowEnd,
+		Dimensions: dimensions,
+	}
+
+	if row.Cost != nil {
+		apiRow.Cost = nullable.NewNullableWithValue(row.Cost.String())
+	} else {
+		apiRow.Cost = nullable.NewNullNullable[api.Numeric]()
+	}
+
+	if row.Detail != "" {
+		apiRow.Detail = lo.ToPtr(row.Detail)
+	}
+
+	return apiRow
+}

api/v3/handlers/featurecost/handler.go

@@ -0,0 +1,42 @@
+package featurecost
+
+import (
+	"context"
+
+	"github.com/openmeterio/openmeter/openmeter/cost"
+	"github.com/openmeterio/openmeter/openmeter/customer"
+	"github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type Handler interface {
+	QueryFeatureCost() QueryFeatureCostHandler
+}
+
+type handler struct {
+	resolveNamespace func(ctx context.Context) (string, error)
+	costService      cost.Service
+	featureConnector feature.FeatureConnector
+	meterService     meter.Service
+	customerService  customer.Service
+	options          []httptransport.HandlerOption
+}
+
+func New(
+	resolveNamespace func(ctx context.Context) (string, error),
+	costService cost.Service,
+	featureConnector feature.FeatureConnector,
+	meterService meter.Service,
+	customerService customer.Service,
+	options ...httptransport.HandlerOption,
+) Handler {
+	return &handler{
+		resolveNamespace: resolveNamespace,
+		costService:      costService,
+		featureConnector: featureConnector,
+		meterService:     meterService,
+		customerService:  customerService,
+		options:          options,
+	}
+}

api/v3/handlers/featurecost/query.go

@@ -0,0 +1,97 @@
+package featurecost
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/api/v3/handlers/meters/query"
+	"github.com/openmeterio/openmeter/api/v3/request"
+	"github.com/openmeterio/openmeter/openmeter/cost"
+	"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"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+type (
+	QueryFeatureCostRequest struct {
+		Namespace string
+		FeatureID string
+		Body      api.MeterQueryRequest
+	}
+	QueryFeatureCostResponse = api.FeatureCostQueryResult
+	QueryFeatureCostParams   = string
+	QueryFeatureCostHandler  httptransport.HandlerWithArgs[QueryFeatureCostRequest, QueryFeatureCostResponse, QueryFeatureCostParams]
+)
+
+func (h *handler) QueryFeatureCost() QueryFeatureCostHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, featureID QueryFeatureCostParams) (QueryFeatureCostRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return QueryFeatureCostRequest{}, err
+			}
+
+			var body api.MeterQueryRequest
+			if err := request.ParseOptionalBody(r, &body); err != nil {
+				return QueryFeatureCostRequest{}, err
+			}
+
+			return QueryFeatureCostRequest{
+				Namespace: ns,
+				FeatureID: featureID,
+				Body:      body,
+			}, nil
+		},
+		func(ctx context.Context, req QueryFeatureCostRequest) (QueryFeatureCostResponse, error) {
+			// Get the feature to find its meter
+			feat, err := h.featureConnector.GetFeature(ctx, req.Namespace, req.FeatureID, feature.IncludeArchivedFeatureFalse)
+			if err != nil {
+				return QueryFeatureCostResponse{}, err
+			}
+
+			if feat.MeterID == nil {
+				return QueryFeatureCostResponse{}, models.NewGenericValidationError(
+					fmt.Errorf("feature %s has no meter associated", feat.Key),
+				)
+			}
+
+			// Get the meter for query param validation
+			m, err := h.meterService.GetMeterByIDOrSlug(ctx, meter.GetMeterInput{
+				Namespace: req.Namespace,
+				IDOrSlug:  *feat.MeterID,
+			})
+			if err != nil {
+				return QueryFeatureCostResponse{}, fmt.Errorf("failed to get meter: %w", err)
+			}
+
+			// Build streaming query params using shared logic
+			params, err := query.BuildQueryParams(ctx, m, req.Body, query.NewCustomerResolver(h.customerService))
+			if err != nil {
+				return QueryFeatureCostResponse{}, err
+			}
+
+			// Query feature cost
+			result, err := h.costService.QueryFeatureCost(ctx, cost.QueryFeatureCostInput{
+				Namespace:   req.Namespace,
+				FeatureID:   feat.ID,
+				QueryParams: params,
+			})
+			if err != nil {
+				return QueryFeatureCostResponse{}, err
+			}
+
+			return ToAPIFeatureCostQueryResult(result, req.Body), nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[QueryFeatureCostResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("query-feature-cost"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/features/convert.go

@@ -0,0 +1,352 @@
+package features
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/alpacahq/alpacadecimal"
+	"github.com/oapi-codegen/nullable"
+	"github.com/samber/lo"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/api/v3/labels"
+	"github.com/openmeterio/openmeter/api/v3/request"
+	"github.com/openmeterio/openmeter/openmeter/llmcost"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	"github.com/openmeterio/openmeter/pkg/filter"
+)
+
+func FromAPIFeatureSortField(ctx context.Context, field string) (feature.FeatureOrderBy, error) {
+	switch field {
+	case "key":
+		return feature.FeatureOrderByKey, nil
+	case "name":
+		return feature.FeatureOrderByName, nil
+	case "created_at":
+		return feature.FeatureOrderByCreatedAt, nil
+	case "updated_at":
+		return feature.FeatureOrderByUpdatedAt, nil
+	default:
+		return "", apierrors.NewUnsupportedSortFieldError(
+			ctx, field, "key", "name", "created_at", "updated_at",
+		)
+	}
+}
+
+func convertFeatureToAPI(f feature.Feature) (api.Feature, error) {
+	resp := api.Feature{
+		Id:          f.ID,
+		Key:         f.Key,
+		Name:        f.Name,
+		Description: f.Description,
+		Labels:      labels.FromMetadata(f.Metadata),
+		CreatedAt:   f.CreatedAt,
+		UpdatedAt:   f.UpdatedAt,
+		DeletedAt:   f.ArchivedAt,
+	}
+
+	if f.MeterID != nil {
+		resp.Meter = &api.FeatureMeterReference{
+			Id: *f.MeterID,
+		}
+
+		if len(f.MeterGroupByFilters) > 0 {
+			filters := convertFiltersToAPI(f.MeterGroupByFilters)
+			resp.Meter.Filters = &filters
+		}
+	}
+
+	if f.UnitCost != nil {
+		apiUnitCost, err := convertUnitCostToAPI(f.UnitCost)
+		if err != nil {
+			return api.Feature{}, fmt.Errorf("failed to convert unit cost: %w", err)
+		}
+		resp.UnitCost = &apiUnitCost
+	}
+
+	return resp, nil
+}
+
+func convertCreateRequestToDomain(ns string, body api.CreateFeatureRequest, meterID *string) (feature.CreateFeatureInputs, error) {
+	metadata, err := labels.ToMetadata(body.Labels)
+	if err != nil {
+		return feature.CreateFeatureInputs{}, fmt.Errorf("failed to convert labels: %w", err)
+	}
+
+	inputs := feature.CreateFeatureInputs{
+		Namespace:   ns,
+		Name:        body.Name,
+		Description: body.Description,
+		Key:         body.Key,
+		MeterID:     meterID,
+		Metadata:    metadata,
+	}
+
+	if body.Meter != nil {
+		if body.Meter.Filters != nil {
+			inputs.MeterGroupByFilters = convertFiltersFromAPI(*body.Meter.Filters)
+		}
+	}
+
+	if body.UnitCost != nil {
+		unitCost, err := convertUnitCostFromAPI(body.UnitCost)
+		if err != nil {
+			return feature.CreateFeatureInputs{}, fmt.Errorf("invalid unit cost: %w", err)
+		}
+		inputs.UnitCost = unitCost
+	}
+
+	return inputs, nil
+}
+
+func convertUpdateRequestToDomain(ns string, featureID string, body api.UpdateFeatureRequest) (feature.UpdateFeatureInputs, error) {
+	input := feature.UpdateFeatureInputs{
+		Namespace: ns,
+		ID:        featureID,
+	}
+
+	if body.UnitCost.IsNull() {
+		input.UnitCost = nullable.NewNullNullable[feature.UnitCost]()
+	} else if body.UnitCost.IsSpecified() {
+		v, err := body.UnitCost.Get()
+		if err != nil {
+			return feature.UpdateFeatureInputs{}, fmt.Errorf("invalid unit cost: %w", err)
+		}
+		unitCost, err := convertUnitCostFromAPI(&v)
+		if err != nil {
+			return feature.UpdateFeatureInputs{}, fmt.Errorf("invalid unit cost: %w", err)
+		}
+		input.UnitCost = nullable.NewNullableWithValue(*unitCost)
+	}
+
+	return input, nil
+}
+
+func convertUnitCostToAPI(u *feature.UnitCost) (api.BillingFeatureUnitCost, error) {
+	var out api.BillingFeatureUnitCost
+
+	switch u.Type {
+	case feature.UnitCostTypeManual:
+		if err := out.FromBillingFeatureManualUnitCost(api.BillingFeatureManualUnitCost{
+			Amount: u.Manual.Amount.String(),
+		}); err != nil {
+			return out, fmt.Errorf("failed to convert manual unit cost: %w", err)
+		}
+	case feature.UnitCostTypeLLM:
+		llmCost := api.BillingFeatureLLMUnitCost{}
+		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(api.BillingFeatureLLMTokenType(u.LLM.TokenType))
+		}
+		if err := out.FromBillingFeatureLLMUnitCost(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 convertUnitCostFromAPI(u *api.BillingFeatureUnitCost) (*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.AsBillingFeatureManualUnitCost()
+		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.AsBillingFeatureLLMUnitCost()
+		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:         string(lo.FromPtrOr(llm.TokenType, "")),
+			},
+		}, nil
+	default:
+		return nil, fmt.Errorf("unknown unit cost type: %s", discriminator)
+	}
+}
+
+func enrichFeatureResponseWithPricing(resp *api.Feature, pricing *llmcost.ModelPricing) {
+	if resp.UnitCost == nil || pricing == nil {
+		return
+	}
+
+	disc, err := resp.UnitCost.Discriminator()
+	if err != nil || disc != "llm" {
+		return
+	}
+
+	llmCost, err := resp.UnitCost.AsBillingFeatureLLMUnitCost()
+	if err != nil {
+		return
+	}
+
+	apiPricing := api.BillingFeatureLLMUnitCostPricing{
+		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.FromBillingFeatureLLMUnitCost(llmCost)
+}
+
+// resolveLLMPricing resolves LLM pricing for a feature from the LLM cost database.
+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
+
+	provider := llmConf.Provider
+	if provider == "" {
+		provider = extractEqFilterValue(feat.MeterGroupByFilters, llmConf.ProviderProperty)
+	}
+	if provider == "" {
+		return nil
+	}
+
+	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
+}
+
+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
+}
+
+func convertFiltersFromAPI(apiFilters map[string]api.QueryFilterStringMapItem) feature.MeterGroupByFilters {
+	result := make(feature.MeterGroupByFilters, len(apiFilters))
+	for k, v := range apiFilters {
+		result[k] = request.ConvertQueryFilterStringMapItem(v)
+	}
+	return result
+}
+
+func convertFiltersToAPI(filters feature.MeterGroupByFilters) map[string]api.QueryFilterStringMapItem {
+	result := make(map[string]api.QueryFilterStringMapItem, len(filters))
+	for k, v := range filters {
+		result[k] = convertFilterStringToAPIMapItem(v)
+	}
+	return result
+}
+
+func convertFilterStringToAPIMapItem(f filter.FilterString) api.QueryFilterStringMapItem {
+	return api.QueryFilterStringMapItem{
+		Exists:    f.Exists,
+		Eq:        f.Eq,
+		Neq:       f.Ne,
+		In:        f.In,
+		Nin:       f.Nin,
+		Contains:  filter.ReverseContainsPattern(f.Like),
+		Ncontains: filter.ReverseContainsPattern(f.Nlike),
+		And:       convertFilterStringListToAPI(f.And),
+		Or:        convertFilterStringListToAPI(f.Or),
+	}
+}
+
+func convertFilterStringListToAPI(filters *[]filter.FilterString) *[]api.QueryFilterString {
+	if filters == nil {
+		return nil
+	}
+	result := make([]api.QueryFilterString, len(*filters))
+	for i, f := range *filters {
+		result[i] = convertFilterStringToAPIQueryFilter(f)
+	}
+	return &result
+}
+
+func convertFilterStringToAPIQueryFilter(f filter.FilterString) api.QueryFilterString {
+	return api.QueryFilterString{
+		Eq:        f.Eq,
+		Neq:       f.Ne,
+		In:        f.In,
+		Nin:       f.Nin,
+		Contains:  filter.ReverseContainsPattern(f.Like),
+		Ncontains: filter.ReverseContainsPattern(f.Nlike),
+		And:       convertFilterStringListToAPI(f.And),
+		Or:        convertFilterStringListToAPI(f.Or),
+	}
+}

api/v3/handlers/features/convert_test.go

@@ -0,0 +1,574 @@
+package features
+
+import (
+	"testing"
+	"time"
+
+	"github.com/alpacahq/alpacadecimal"
+	"github.com/oapi-codegen/nullable"
+	"github.com/samber/lo"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/labels"
+	"github.com/openmeterio/openmeter/openmeter/llmcost"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	"github.com/openmeterio/openmeter/pkg/filter"
+)
+
+func TestConvertUnitCostToAPI(t *testing.T) {
+	t.Run("manual unit cost", func(t *testing.T) {
+		uc := &feature.UnitCost{
+			Type: feature.UnitCostTypeManual,
+			Manual: &feature.ManualUnitCost{
+				Amount: alpacadecimal.NewFromFloat(0.005),
+			},
+		}
+
+		result, err := convertUnitCostToAPI(uc)
+		require.NoError(t, err)
+
+		disc, err := result.Discriminator()
+		require.NoError(t, err)
+		assert.Equal(t, "manual", disc)
+
+		manual, err := result.AsBillingFeatureManualUnitCost()
+		require.NoError(t, err)
+		assert.Equal(t, api.Numeric("0.005"), manual.Amount)
+	})
+
+	t.Run("llm unit cost with properties", func(t *testing.T) {
+		uc := &feature.UnitCost{
+			Type: feature.UnitCostTypeLLM,
+			LLM: &feature.LLMUnitCost{
+				ProviderProperty:  "provider",
+				ModelProperty:     "model",
+				TokenTypeProperty: "type",
+			},
+		}
+
+		result, err := convertUnitCostToAPI(uc)
+		require.NoError(t, err)
+
+		disc, err := result.Discriminator()
+		require.NoError(t, err)
+		assert.Equal(t, "llm", disc)
+
+		llm, err := result.AsBillingFeatureLLMUnitCost()
+		require.NoError(t, err)
+		assert.Equal(t, lo.ToPtr("provider"), llm.ProviderProperty)
+		assert.Equal(t, lo.ToPtr("model"), llm.ModelProperty)
+		assert.Equal(t, lo.ToPtr("type"), llm.TokenTypeProperty)
+		assert.Nil(t, llm.Provider)
+		assert.Nil(t, llm.Model)
+		assert.Nil(t, llm.TokenType)
+	})
+
+	t.Run("llm unit cost with static values", func(t *testing.T) {
+		uc := &feature.UnitCost{
+			Type: feature.UnitCostTypeLLM,
+			LLM: &feature.LLMUnitCost{
+				Provider:  "openai",
+				Model:     "gpt-4",
+				TokenType: "input",
+			},
+		}
+
+		result, err := convertUnitCostToAPI(uc)
+		require.NoError(t, err)
+
+		llm, err := result.AsBillingFeatureLLMUnitCost()
+		require.NoError(t, err)
+		assert.Equal(t, lo.ToPtr("openai"), llm.Provider)
+		assert.Equal(t, lo.ToPtr("gpt-4"), llm.Model)
+		assert.Equal(t, lo.ToPtr(api.BillingFeatureLLMTokenTypeInput), llm.TokenType)
+		assert.Nil(t, llm.ProviderProperty)
+		assert.Nil(t, llm.ModelProperty)
+		assert.Nil(t, llm.TokenTypeProperty)
+	})
+
+	t.Run("unknown type returns error", func(t *testing.T) {
+		uc := &feature.UnitCost{Type: "unknown"}
+		_, err := convertUnitCostToAPI(uc)
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "unknown unit cost type")
+	})
+}
+
+func TestConvertUnitCostFromAPI(t *testing.T) {
+	t.Run("manual unit cost", func(t *testing.T) {
+		var apiUC api.BillingFeatureUnitCost
+		err := apiUC.FromBillingFeatureManualUnitCost(api.BillingFeatureManualUnitCost{
+			Amount: "0.123",
+		})
+		require.NoError(t, err)
+
+		result, err := convertUnitCostFromAPI(&apiUC)
+		require.NoError(t, err)
+		assert.Equal(t, feature.UnitCostTypeManual, result.Type)
+		assert.NotNil(t, result.Manual)
+		assert.Equal(t, "0.123", result.Manual.Amount.String())
+		assert.Nil(t, result.LLM)
+	})
+
+	t.Run("llm unit cost with properties", func(t *testing.T) {
+		var apiUC api.BillingFeatureUnitCost
+		err := apiUC.FromBillingFeatureLLMUnitCost(api.BillingFeatureLLMUnitCost{
+			ProviderProperty:  lo.ToPtr("provider"),
+			ModelProperty:     lo.ToPtr("model"),
+			TokenTypeProperty: lo.ToPtr("type"),
+		})
+		require.NoError(t, err)
+
+		result, err := convertUnitCostFromAPI(&apiUC)
+		require.NoError(t, err)
+		assert.Equal(t, feature.UnitCostTypeLLM, result.Type)
+		assert.NotNil(t, result.LLM)
+		assert.Equal(t, "provider", result.LLM.ProviderProperty)
+		assert.Equal(t, "model", result.LLM.ModelProperty)
+		assert.Equal(t, "type", result.LLM.TokenTypeProperty)
+		assert.Empty(t, result.LLM.Provider)
+		assert.Empty(t, result.LLM.Model)
+		assert.Empty(t, result.LLM.TokenType)
+	})
+
+	t.Run("llm unit cost with static values", func(t *testing.T) {
+		var apiUC api.BillingFeatureUnitCost
+		err := apiUC.FromBillingFeatureLLMUnitCost(api.BillingFeatureLLMUnitCost{
+			Provider:  lo.ToPtr("anthropic"),
+			Model:     lo.ToPtr("claude-3-5-sonnet"),
+			TokenType: lo.ToPtr(api.BillingFeatureLLMTokenTypeOutput),
+		})
+		require.NoError(t, err)
+
+		result, err := convertUnitCostFromAPI(&apiUC)
+		require.NoError(t, err)
+		assert.Equal(t, feature.UnitCostTypeLLM, result.Type)
+		assert.Equal(t, "anthropic", result.LLM.Provider)
+		assert.Equal(t, "claude-3-5-sonnet", result.LLM.Model)
+		assert.Equal(t, "output", result.LLM.TokenType)
+	})
+}
+
+func TestConvertUnitCostRoundTrip(t *testing.T) {
+	t.Run("manual round trip", func(t *testing.T) {
+		original := &feature.UnitCost{
+			Type: feature.UnitCostTypeManual,
+			Manual: &feature.ManualUnitCost{
+				Amount: alpacadecimal.NewFromFloat(1.50),
+			},
+		}
+
+		apiUC, err := convertUnitCostToAPI(original)
+		require.NoError(t, err)
+
+		result, err := convertUnitCostFromAPI(&apiUC)
+		require.NoError(t, err)
+
+		assert.Equal(t, original.Type, result.Type)
+		assert.True(t, original.Manual.Amount.Equal(result.Manual.Amount))
+	})
+
+	t.Run("llm round trip", func(t *testing.T) {
+		original := &feature.UnitCost{
+			Type: feature.UnitCostTypeLLM,
+			LLM: &feature.LLMUnitCost{
+				ProviderProperty:  "provider",
+				ModelProperty:     "model",
+				TokenTypeProperty: "type",
+			},
+		}
+
+		apiUC, err := convertUnitCostToAPI(original)
+		require.NoError(t, err)
+
+		result, err := convertUnitCostFromAPI(&apiUC)
+		require.NoError(t, err)
+
+		assert.Equal(t, original.Type, result.Type)
+		assert.Equal(t, original.LLM, result.LLM)
+	})
+}
+
+func TestConvertFeatureToAPI(t *testing.T) {
+	now := time.Now().UTC().Truncate(time.Millisecond)
+
+	t.Run("feature without meter or unit cost", func(t *testing.T) {
+		f := feature.Feature{
+			Namespace: "default",
+			ID:        "feat-1",
+			Name:      "My Feature",
+			Key:       "my_feature",
+			Metadata:  map[string]string{"env": "test"},
+			CreatedAt: now,
+			UpdatedAt: now,
+		}
+
+		result, err := convertFeatureToAPI(f)
+		require.NoError(t, err)
+		assert.Equal(t, "feat-1", result.Id)
+		assert.Equal(t, api.ResourceKey("my_feature"), result.Key)
+		assert.Equal(t, "My Feature", result.Name)
+		assert.Nil(t, result.Meter)
+		assert.Nil(t, result.UnitCost)
+		assert.Nil(t, result.DeletedAt)
+		require.NotNil(t, result.Labels)
+		assert.Equal(t, "test", (*result.Labels)["env"])
+	})
+
+	t.Run("feature with meter and filters", func(t *testing.T) {
+		f := feature.Feature{
+			Namespace: "default",
+			ID:        "feat-2",
+			Name:      "Token Feature",
+			Key:       "tokens",
+			MeterID:   lo.ToPtr("01ARZ3NDEKTSV4RRFFQ69G5FAV"),
+			MeterGroupByFilters: feature.MeterGroupByFilters{
+				"provider": {Eq: lo.ToPtr("openai")},
+			},
+			CreatedAt: now,
+			UpdatedAt: now,
+		}
+
+		result, err := convertFeatureToAPI(f)
+		require.NoError(t, err)
+		require.NotNil(t, result.Meter)
+		assert.Equal(t, api.ULID("01ARZ3NDEKTSV4RRFFQ69G5FAV"), result.Meter.Id)
+		require.NotNil(t, result.Meter.Filters)
+		filterMap := *result.Meter.Filters
+		assert.Equal(t, lo.ToPtr("openai"), filterMap["provider"].Eq)
+	})
+
+	t.Run("feature with manual unit cost", func(t *testing.T) {
+		f := feature.Feature{
+			Namespace: "default",
+			ID:        "feat-3",
+			Name:      "API Calls",
+			Key:       "api_calls",
+			MeterID:   lo.ToPtr("api_requests"),
+			UnitCost: &feature.UnitCost{
+				Type: feature.UnitCostTypeManual,
+				Manual: &feature.ManualUnitCost{
+					Amount: alpacadecimal.NewFromFloat(0.01),
+				},
+			},
+			CreatedAt: now,
+			UpdatedAt: now,
+		}
+
+		result, err := convertFeatureToAPI(f)
+		require.NoError(t, err)
+		require.NotNil(t, result.UnitCost)
+
+		disc, err := result.UnitCost.Discriminator()
+		require.NoError(t, err)
+		assert.Equal(t, "manual", disc)
+	})
+
+	t.Run("feature with archived at", func(t *testing.T) {
+		archived := now.Add(-time.Hour)
+		f := feature.Feature{
+			Namespace:  "default",
+			ID:         "feat-4",
+			Name:       "Archived",
+			Key:        "archived",
+			ArchivedAt: &archived,
+			CreatedAt:  now,
+			UpdatedAt:  now,
+		}
+
+		result, err := convertFeatureToAPI(f)
+		require.NoError(t, err)
+		require.NotNil(t, result.DeletedAt)
+		assert.Equal(t, archived, *result.DeletedAt)
+	})
+}
+
+func TestConvertCreateRequestToDomain(t *testing.T) {
+	t.Run("minimal request without meter", func(t *testing.T) {
+		body := api.CreateFeatureRequest{
+			Key:  "my_key",
+			Name: "My Feature",
+		}
+
+		result, err := convertCreateRequestToDomain("test-ns", body, nil)
+		require.NoError(t, err)
+		assert.Equal(t, "test-ns", result.Namespace)
+		assert.Equal(t, "my_key", result.Key)
+		assert.Equal(t, "My Feature", result.Name)
+		assert.Nil(t, result.MeterID)
+		assert.Nil(t, result.UnitCost)
+	})
+
+	t.Run("with meter ID and filters", func(t *testing.T) {
+		meterID := "01ARZ3NDEKTSV4RRFFQ69G5FAV"
+		body := api.CreateFeatureRequest{
+			Key:  "tokens",
+			Name: "Tokens",
+			Meter: &api.FeatureMeterReference{
+				Id: api.ULID("01ARZ3NDEKTSV4RRFFQ69G5FAV"),
+				Filters: &map[string]api.QueryFilterStringMapItem{
+					"model": {Eq: lo.ToPtr("gpt-4")},
+				},
+			},
+		}
+
+		result, err := convertCreateRequestToDomain("ns", body, &meterID)
+		require.NoError(t, err)
+		require.NotNil(t, result.MeterID)
+		assert.Equal(t, "01ARZ3NDEKTSV4RRFFQ69G5FAV", *result.MeterID)
+		require.NotNil(t, result.MeterGroupByFilters)
+		assert.Equal(t, lo.ToPtr("gpt-4"), result.MeterGroupByFilters["model"].Eq)
+	})
+
+	t.Run("with manual unit cost", func(t *testing.T) {
+		var uc api.BillingFeatureUnitCost
+		err := uc.FromBillingFeatureManualUnitCost(api.BillingFeatureManualUnitCost{Amount: "0.05"})
+		require.NoError(t, err)
+
+		body := api.CreateFeatureRequest{
+			Key:      "feat",
+			Name:     "Feature",
+			UnitCost: &uc,
+		}
+
+		result, err := convertCreateRequestToDomain("ns", body, nil)
+		require.NoError(t, err)
+		require.NotNil(t, result.UnitCost)
+		assert.Equal(t, feature.UnitCostTypeManual, result.UnitCost.Type)
+		assert.Equal(t, "0.05", result.UnitCost.Manual.Amount.String())
+	})
+
+	t.Run("with labels", func(t *testing.T) {
+		labels := api.Labels{"env": "prod", "team": "billing"}
+		body := api.CreateFeatureRequest{
+			Key:    "feat",
+			Name:   "Feature",
+			Labels: &labels,
+		}
+
+		result, err := convertCreateRequestToDomain("ns", body, nil)
+		require.NoError(t, err)
+		assert.Equal(t, "prod", result.Metadata["env"])
+		assert.Equal(t, "billing", result.Metadata["team"])
+	})
+}
+
+func TestConvertUpdateRequestToDomain(t *testing.T) {
+	t.Run("with unit cost value", func(t *testing.T) {
+		var uc api.BillingFeatureUnitCost
+		err := uc.FromBillingFeatureManualUnitCost(api.BillingFeatureManualUnitCost{Amount: "0.05"})
+		require.NoError(t, err)
+
+		body := api.UpdateFeatureRequest{UnitCost: nullable.NewNullableWithValue(uc)}
+		result, err := convertUpdateRequestToDomain("ns", "feat-1", body)
+		require.NoError(t, err)
+		assert.Equal(t, "ns", result.Namespace)
+		assert.Equal(t, "feat-1", result.ID)
+		assert.True(t, result.UnitCost.IsSpecified())
+		assert.False(t, result.UnitCost.IsNull())
+		unitCost, err := result.UnitCost.Get()
+		require.NoError(t, err)
+		assert.Equal(t, feature.UnitCostTypeManual, unitCost.Type)
+		assert.Equal(t, "0.05", unitCost.Manual.Amount.String())
+	})
+
+	t.Run("with explicit null clears unit cost", func(t *testing.T) {
+		body := api.UpdateFeatureRequest{UnitCost: nullable.NewNullNullable[api.BillingFeatureUnitCost]()}
+		result, err := convertUpdateRequestToDomain("ns", "feat-1", body)
+		require.NoError(t, err)
+		assert.True(t, result.UnitCost.IsNull())
+	})
+
+	t.Run("with omitted unit cost", func(t *testing.T) {
+		body := api.UpdateFeatureRequest{}
+		result, err := convertUpdateRequestToDomain("ns", "feat-1", body)
+		require.NoError(t, err)
+		assert.False(t, result.UnitCost.IsSpecified())
+	})
+}
+
+func TestEnrichFeatureResponseWithPricing(t *testing.T) {
+	t.Run("adds pricing to llm unit cost", func(t *testing.T) {
+		var uc api.BillingFeatureUnitCost
+		err := uc.FromBillingFeatureLLMUnitCost(api.BillingFeatureLLMUnitCost{
+			ProviderProperty: lo.ToPtr("provider"),
+			ModelProperty:    lo.ToPtr("model"),
+		})
+		require.NoError(t, err)
+
+		resp := &api.Feature{UnitCost: &uc}
+		pricing := &llmcost.ModelPricing{
+			InputPerToken:  alpacadecimal.NewFromFloat(0.00001),
+			OutputPerToken: alpacadecimal.NewFromFloat(0.00003),
+		}
+
+		enrichFeatureResponseWithPricing(resp, pricing)
+
+		llm, err := resp.UnitCost.AsBillingFeatureLLMUnitCost()
+		require.NoError(t, err)
+		require.NotNil(t, llm.Pricing)
+		assert.Equal(t, api.Numeric("0.00001"), llm.Pricing.InputPerToken)
+		assert.Equal(t, api.Numeric("0.00003"), llm.Pricing.OutputPerToken)
+		assert.Nil(t, llm.Pricing.CacheReadPerToken)
+	})
+
+	t.Run("adds optional pricing fields", func(t *testing.T) {
+		var uc api.BillingFeatureUnitCost
+		err := uc.FromBillingFeatureLLMUnitCost(api.BillingFeatureLLMUnitCost{
+			Provider: lo.ToPtr("openai"),
+			Model:    lo.ToPtr("gpt-4"),
+		})
+		require.NoError(t, err)
+
+		resp := &api.Feature{UnitCost: &uc}
+		pricing := &llmcost.ModelPricing{
+			InputPerToken:     alpacadecimal.NewFromFloat(0.00001),
+			OutputPerToken:    alpacadecimal.NewFromFloat(0.00003),
+			CacheReadPerToken: lo.ToPtr(alpacadecimal.NewFromFloat(0.000005)),
+			ReasoningPerToken: lo.ToPtr(alpacadecimal.NewFromFloat(0.00006)),
+		}
+
+		enrichFeatureResponseWithPricing(resp, pricing)
+
+		llm, err := resp.UnitCost.AsBillingFeatureLLMUnitCost()
+		require.NoError(t, err)
+		require.NotNil(t, llm.Pricing.CacheReadPerToken)
+		assert.Equal(t, api.Numeric("0.000005"), *llm.Pricing.CacheReadPerToken)
+		require.NotNil(t, llm.Pricing.ReasoningPerToken)
+		assert.Equal(t, api.Numeric("0.00006"), *llm.Pricing.ReasoningPerToken)
+		assert.Nil(t, llm.Pricing.CacheWritePerToken)
+	})
+
+	t.Run("no-op when unit cost is manual", func(t *testing.T) {
+		var uc api.BillingFeatureUnitCost
+		err := uc.FromBillingFeatureManualUnitCost(api.BillingFeatureManualUnitCost{Amount: "0.005"})
+		require.NoError(t, err)
+		resp := &api.Feature{UnitCost: &uc}
+
+		enrichFeatureResponseWithPricing(resp, &llmcost.ModelPricing{
+			InputPerToken:  alpacadecimal.NewFromFloat(0.00001),
+			OutputPerToken: alpacadecimal.NewFromFloat(0.00003),
+		})
+
+		// Manual cost should be unchanged
+		manual, err := resp.UnitCost.AsBillingFeatureManualUnitCost()
+		require.NoError(t, err)
+		assert.Equal(t, api.Numeric("0.005"), manual.Amount)
+	})
+
+	t.Run("no-op when unit cost is nil", func(t *testing.T) {
+		resp := &api.Feature{}
+		enrichFeatureResponseWithPricing(resp, &llmcost.ModelPricing{})
+		assert.Nil(t, resp.UnitCost)
+	})
+
+	t.Run("no-op when pricing is nil", func(t *testing.T) {
+		var uc api.BillingFeatureUnitCost
+		err := uc.FromBillingFeatureLLMUnitCost(api.BillingFeatureLLMUnitCost{})
+		require.NoError(t, err)
+		resp := &api.Feature{UnitCost: &uc}
+		enrichFeatureResponseWithPricing(resp, nil)
+
+		llm, err := resp.UnitCost.AsBillingFeatureLLMUnitCost()
+		require.NoError(t, err)
+		assert.Nil(t, llm.Pricing)
+	})
+}
+
+func TestExtractEqFilterValue(t *testing.T) {
+	t.Run("returns value for eq filter", func(t *testing.T) {
+		filters := feature.MeterGroupByFilters{
+			"provider": {Eq: lo.ToPtr("openai")},
+		}
+		assert.Equal(t, "openai", extractEqFilterValue(filters, "provider"))
+	})
+
+	t.Run("returns empty for missing key", func(t *testing.T) {
+		filters := feature.MeterGroupByFilters{
+			"provider": {Eq: lo.ToPtr("openai")},
+		}
+		assert.Equal(t, "", extractEqFilterValue(filters, "model"))
+	})
+
+	t.Run("returns empty for non-eq filter", func(t *testing.T) {
+		filters := feature.MeterGroupByFilters{
+			"provider": {In: &[]string{"openai", "anthropic"}},
+		}
+		assert.Equal(t, "", extractEqFilterValue(filters, "provider"))
+	})
+
+	t.Run("returns empty for nil filters", func(t *testing.T) {
+		assert.Equal(t, "", extractEqFilterValue(nil, "key"))
+	})
+}
+
+func TestConvertFiltersRoundTrip(t *testing.T) {
+	original := feature.MeterGroupByFilters{
+		"provider": {Eq: lo.ToPtr("openai")},
+		"model":    {In: &[]string{"gpt-4", "gpt-4o"}},
+	}
+
+	apiFilters := convertFiltersToAPI(original)
+	assert.Len(t, apiFilters, 2)
+	assert.Equal(t, lo.ToPtr("openai"), apiFilters["provider"].Eq)
+	assert.Equal(t, &[]string{"gpt-4", "gpt-4o"}, apiFilters["model"].In)
+
+	roundTripped := convertFiltersFromAPI(apiFilters)
+	assert.Equal(t, lo.ToPtr("openai"), roundTripped["provider"].Eq)
+	assert.Equal(t, &[]string{"gpt-4", "gpt-4o"}, roundTripped["model"].In)
+}
+
+func TestConvertMetadataLabels(t *testing.T) {
+	t.Run("metadata to labels", func(t *testing.T) {
+		l := labels.FromMetadata(map[string]string{"a": "1", "b": "2"})
+		require.NotNil(t, l)
+		assert.Equal(t, "1", (*l)["a"])
+		assert.Equal(t, "2", (*l)["b"])
+	})
+
+	t.Run("nil metadata returns nil labels", func(t *testing.T) {
+		l := labels.FromMetadata((map[string]string)(nil))
+		assert.Empty(t, l)
+	})
+
+	t.Run("labels to metadata", func(t *testing.T) {
+		l := api.Labels{"x": "y"}
+		meta, err := labels.ToMetadata(&l)
+		assert.NoError(t, err)
+		assert.Equal(t, "y", meta["x"])
+	})
+
+	t.Run("nil labels returns nil metadata", func(t *testing.T) {
+		meta, err := labels.ToMetadata(nil)
+		assert.NoError(t, err)
+		assert.Nil(t, meta)
+	})
+}
+
+func TestConvertFilterStringToAPIMapItem(t *testing.T) {
+	t.Run("eq filter", func(t *testing.T) {
+		f := filter.FilterString{Eq: lo.ToPtr("val")}
+		result := convertFilterStringToAPIMapItem(f)
+		assert.Equal(t, lo.ToPtr("val"), result.Eq)
+	})
+
+	t.Run("in filter", func(t *testing.T) {
+		f := filter.FilterString{In: &[]string{"a", "b"}}
+		result := convertFilterStringToAPIMapItem(f)
+		assert.Equal(t, &[]string{"a", "b"}, result.In)
+	})
+
+	t.Run("ne filter", func(t *testing.T) {
+		f := filter.FilterString{Ne: lo.ToPtr("excluded")}
+		result := convertFilterStringToAPIMapItem(f)
+		assert.Equal(t, lo.ToPtr("excluded"), result.Neq)
+	})
+
+	t.Run("exists filter", func(t *testing.T) {
+		f := filter.FilterString{Exists: lo.ToPtr(true)}
+		result := convertFilterStringToAPIMapItem(f)
+		assert.Equal(t, lo.ToPtr(true), result.Exists)
+	})
+}

api/v3/handlers/features/create.go

@@ -0,0 +1,95 @@
+package features
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/api/v3/request"
+	"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"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+type (
+	CreateFeatureRequest  = feature.CreateFeatureInputs
+	CreateFeatureResponse = api.Feature
+	CreateFeatureHandler  httptransport.Handler[CreateFeatureRequest, CreateFeatureResponse]
+)
+
+func (h *handler) CreateFeature() CreateFeatureHandler {
+	return httptransport.NewHandler(
+		func(ctx context.Context, r *http.Request) (CreateFeatureRequest, error) {
+			body := api.CreateFeatureRequest{}
+			if err := request.ParseBody(r, &body); err != nil {
+				return CreateFeatureRequest{}, err
+			}
+
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return CreateFeatureRequest{}, err
+			}
+
+			// Resolve and validate the meter reference.
+			var meterID *string
+			if body.Meter != nil {
+				if body.Meter.Id == "" {
+					return CreateFeatureRequest{}, models.NewGenericValidationError(
+						fmt.Errorf("meter id is required"),
+					)
+				}
+
+				m, err := h.meterService.GetMeterByIDOrSlug(ctx, meter.GetMeterInput{
+					Namespace: ns,
+					IDOrSlug:  body.Meter.Id,
+				})
+				if err != nil {
+					return CreateFeatureRequest{}, err
+				}
+				meterID = &m.ID
+
+				// Validate meter filters.
+				if body.Meter.Filters != nil {
+					if err := validateMeterFilters(*body.Meter.Filters, m); err != nil {
+						return CreateFeatureRequest{}, err
+					}
+				}
+			}
+
+			return convertCreateRequestToDomain(ns, body, meterID)
+		},
+		func(ctx context.Context, req CreateFeatureRequest) (CreateFeatureResponse, error) {
+			created, err := h.connector.CreateFeature(ctx, req)
+			if err != nil {
+				return CreateFeatureResponse{}, err
+			}
+
+			return convertFeatureToAPI(created)
+		},
+		commonhttp.JSONResponseEncoderWithStatus[CreateFeatureResponse](http.StatusCreated),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("create-feature"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+			httptransport.WithErrorEncoder(errorEncoder()),
+		)...,
+	)
+}
+
+// validateMeterFilters validates that filter keys exist in the meter's dimensions.
+// The single-operator invariant on each filter value is enforced downstream by
+// feature.MeterGroupByFilters.Validate.
+func validateMeterFilters(filters map[string]api.QueryFilterStringMapItem, m meter.Meter) error {
+	for k := range filters {
+		if _, ok := m.GroupBy[k]; !ok {
+			return models.NewGenericValidationError(
+				fmt.Errorf("filter key %q is not a valid dimension of meter %q", k, m.Key),
+			)
+		}
+	}
+	return nil
+}

api/v3/handlers/features/create_test.go

@@ -0,0 +1,60 @@
+package features
+
+import (
+	"testing"
+
+	"github.com/samber/lo"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/openmeter/meter"
+)
+
+func TestValidateMeterFilters(t *testing.T) {
+	testMeter := meter.Meter{
+		Key: "tokens_total",
+		GroupBy: map[string]string{
+			"provider": "$.provider",
+			"model":    "$.model",
+			"type":     "$.type",
+		},
+	}
+
+	t.Run("valid filters", func(t *testing.T) {
+		filters := map[string]api.QueryFilterStringMapItem{
+			"provider": {Eq: lo.ToPtr("openai")},
+			"model":    {In: &[]string{"gpt-4", "gpt-4o"}},
+		}
+
+		err := validateMeterFilters(filters, testMeter)
+		require.NoError(t, err)
+	})
+
+	t.Run("invalid dimension key", func(t *testing.T) {
+		filters := map[string]api.QueryFilterStringMapItem{
+			"nonexistent": {Eq: lo.ToPtr("value")},
+		}
+
+		err := validateMeterFilters(filters, testMeter)
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "nonexistent")
+		assert.Contains(t, err.Error(), "not a valid dimension")
+	})
+
+	t.Run("empty filters", func(t *testing.T) {
+		err := validateMeterFilters(map[string]api.QueryFilterStringMapItem{}, testMeter)
+		require.NoError(t, err)
+	})
+
+	t.Run("mix of valid and invalid keys", func(t *testing.T) {
+		filters := map[string]api.QueryFilterStringMapItem{
+			"provider": {Eq: lo.ToPtr("openai")},
+			"bad_key":  {Eq: lo.ToPtr("value")},
+		}
+
+		err := validateMeterFilters(filters, testMeter)
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), "bad_key")
+	})
+}

api/v3/handlers/features/delete.go

@@ -0,0 +1,49 @@
+package features
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+type (
+	DeleteFeatureRequest  = models.NamespacedID
+	DeleteFeatureResponse = interface{}
+	DeleteFeatureParams   = string
+	DeleteFeatureHandler  httptransport.HandlerWithArgs[DeleteFeatureRequest, DeleteFeatureResponse, DeleteFeatureParams]
+)
+
+func (h *handler) DeleteFeature() DeleteFeatureHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, featureID DeleteFeatureParams) (DeleteFeatureRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return DeleteFeatureRequest{}, err
+			}
+
+			return DeleteFeatureRequest{
+				Namespace: ns,
+				ID:        featureID,
+			}, nil
+		},
+		func(ctx context.Context, req DeleteFeatureRequest) (DeleteFeatureResponse, error) {
+			err := h.connector.ArchiveFeature(ctx, req)
+			if err != nil {
+				return nil, err
+			}
+
+			return nil, nil
+		},
+		commonhttp.EmptyResponseEncoder[DeleteFeatureResponse](http.StatusNoContent),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("delete-feature"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+			httptransport.WithErrorEncoder(errorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/features/error_encoder.go

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

api/v3/handlers/features/get.go

@@ -0,0 +1,66 @@
+package features
+
+import (
+	"context"
+	"net/http"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type (
+	GetFeatureRequest struct {
+		Namespace string
+		IDOrKey   string
+	}
+	GetFeatureResponse = api.Feature
+	GetFeatureParams   = string
+	GetFeatureHandler  httptransport.HandlerWithArgs[GetFeatureRequest, GetFeatureResponse, GetFeatureParams]
+)
+
+func (h *handler) GetFeature() GetFeatureHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, featureID GetFeatureParams) (GetFeatureRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return GetFeatureRequest{}, err
+			}
+
+			return GetFeatureRequest{
+				Namespace: ns,
+				IDOrKey:   featureID,
+			}, nil
+		},
+		func(ctx context.Context, req GetFeatureRequest) (GetFeatureResponse, error) {
+			feat, err := h.connector.GetFeature(ctx, req.Namespace, req.IDOrKey, feature.IncludeArchivedFeatureFalse)
+			if err != nil {
+				return GetFeatureResponse{}, err
+			}
+
+			resp, err := convertFeatureToAPI(*feat)
+			if err != nil {
+				return GetFeatureResponse{}, err
+			}
+
+			// Resolve LLM pricing if applicable
+			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.JSONResponseEncoderWithStatus[GetFeatureResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("get-feature"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+			httptransport.WithErrorEncoder(errorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/features/handler.go

@@ -0,0 +1,42 @@
+package features
+
+import (
+	"context"
+
+	"github.com/openmeterio/openmeter/openmeter/llmcost"
+	"github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type Handler interface {
+	ListFeatures() ListFeaturesHandler
+	GetFeature() GetFeatureHandler
+	CreateFeature() CreateFeatureHandler
+	UpdateFeature() UpdateFeatureHandler
+	DeleteFeature() DeleteFeatureHandler
+}
+
+type handler struct {
+	resolveNamespace func(ctx context.Context) (string, error)
+	connector        feature.FeatureConnector
+	meterService     meter.Service
+	llmcostService   llmcost.Service
+	options          []httptransport.HandlerOption
+}
+
+func New(
+	resolveNamespace func(ctx context.Context) (string, error),
+	connector feature.FeatureConnector,
+	meterService meter.Service,
+	llmcostService llmcost.Service,
+	options ...httptransport.HandlerOption,
+) Handler {
+	return &handler{
+		resolveNamespace: resolveNamespace,
+		connector:        connector,
+		meterService:     meterService,
+		llmcostService:   llmcostService,
+		options:          options,
+	}
+}

api/v3/handlers/features/list.go

@@ -0,0 +1,131 @@
+package features
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/samber/lo"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/api/v3/filters"
+	"github.com/openmeterio/openmeter/api/v3/request"
+	"github.com/openmeterio/openmeter/api/v3/response"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+)
+
+type (
+	ListFeaturesRequest  = feature.ListFeaturesParams
+	ListFeaturesResponse = response.PagePaginationResponse[api.Feature]
+	ListFeaturesParams   = api.ListFeaturesParams
+	ListFeaturesHandler  httptransport.HandlerWithArgs[ListFeaturesRequest, ListFeaturesResponse, ListFeaturesParams]
+)
+
+func (h *handler) ListFeatures() ListFeaturesHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, params ListFeaturesParams) (ListFeaturesRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return ListFeaturesRequest{}, err
+			}
+
+			page := pagination.NewPage(1, 20)
+			if params.Page != nil {
+				page = pagination.NewPage(
+					lo.FromPtrOr(params.Page.Number, 1),
+					lo.FromPtrOr(params.Page.Size, 20),
+				)
+			}
+
+			if err := page.Validate(); err != nil {
+				return ListFeaturesRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+					apierrors.InvalidParameter{
+						Field:  "page",
+						Reason: err.Error(),
+						Source: apierrors.InvalidParamSourceQuery,
+					},
+				})
+			}
+
+			req := ListFeaturesRequest{
+				Namespace: ns,
+				Page:      page,
+			}
+
+			if params.Filter != nil {
+				meterIDs, err := filters.FromAPIFilterULID(params.Filter.MeterId)
+				if err != nil {
+					return ListFeaturesRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[meter_id]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.MeterIDs = meterIDs
+
+				key, err := filters.FromAPIFilterString(params.Filter.Key)
+				if err != nil {
+					return ListFeaturesRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[key]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.Key = key
+
+				name, err := filters.FromAPIFilterString(params.Filter.Name)
+				if err != nil {
+					return ListFeaturesRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[name]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.Name = name
+			}
+
+			if params.Sort != nil {
+				sort, err := request.ParseSortBy(*params.Sort)
+				if err != nil {
+					return ListFeaturesRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "sort", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+
+				orderBy, err := FromAPIFeatureSortField(ctx, sort.Field)
+				if err != nil {
+					return ListFeaturesRequest{}, err
+				}
+				req.OrderBy = orderBy
+				req.Order = sort.Order.ToSortxOrder()
+			}
+
+			return req, nil
+		},
+		func(ctx context.Context, req ListFeaturesRequest) (ListFeaturesResponse, error) {
+			result, err := h.connector.ListFeatures(ctx, req)
+			if err != nil {
+				return ListFeaturesResponse{}, err
+			}
+
+			items := make([]api.Feature, 0, len(result.Items))
+			for _, f := range result.Items {
+				apiFeature, err := convertFeatureToAPI(f)
+				if err != nil {
+					return ListFeaturesResponse{}, err
+				}
+				items = append(items, apiFeature)
+			}
+
+			return response.NewPagePaginationResponse(items, response.PageMetaPage{
+				Size:   req.Page.PageSize,
+				Number: req.Page.PageNumber,
+				Total:  lo.ToPtr(result.TotalCount),
+			}), nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[ListFeaturesResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("list-features"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+			httptransport.WithErrorEncoder(errorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/features/update.go

@@ -0,0 +1,66 @@
+package features
+
+import (
+	"context"
+	"net/http"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/api/v3/request"
+	"github.com/openmeterio/openmeter/openmeter/productcatalog/feature"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type (
+	UpdateFeatureRequest  = feature.UpdateFeatureInputs
+	UpdateFeatureResponse = api.Feature
+	UpdateFeatureParams   = string
+	UpdateFeatureHandler  httptransport.HandlerWithArgs[UpdateFeatureRequest, UpdateFeatureResponse, UpdateFeatureParams]
+)
+
+func (h *handler) UpdateFeature() UpdateFeatureHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, featureID UpdateFeatureParams) (UpdateFeatureRequest, error) {
+			body := api.UpdateFeatureRequest{}
+			if err := request.ParseBody(r, &body); err != nil {
+				return UpdateFeatureRequest{}, err
+			}
+
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return UpdateFeatureRequest{}, err
+			}
+
+			return convertUpdateRequestToDomain(ns, featureID, body)
+		},
+		func(ctx context.Context, req UpdateFeatureRequest) (UpdateFeatureResponse, error) {
+			updated, err := h.connector.UpdateFeature(ctx, req)
+			if err != nil {
+				return UpdateFeatureResponse{}, err
+			}
+
+			resp, err := convertFeatureToAPI(updated)
+			if err != nil {
+				return UpdateFeatureResponse{}, err
+			}
+
+			// Resolve LLM pricing if applicable
+			if updated.UnitCost != nil && updated.UnitCost.Type == feature.UnitCostTypeLLM && h.llmcostService != nil {
+				pricing := resolveLLMPricing(ctx, h.llmcostService, &updated)
+				if pricing != nil {
+					enrichFeatureResponseWithPricing(&resp, pricing)
+				}
+			}
+
+			return resp, nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[UpdateFeatureResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("update-feature"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+			httptransport.WithErrorEncoder(errorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/governance/handler.go

@@ -0,0 +1,30 @@
+package governance
+
+import (
+	"context"
+
+	"github.com/openmeterio/openmeter/openmeter/governance"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type Handler interface {
+	QueryGovernanceAccess() QueryGovernanceAccessHandler
+}
+
+type handler struct {
+	resolveNamespace  func(ctx context.Context) (string, error)
+	governanceService governance.Service
+	options           []httptransport.HandlerOption
+}
+
+func New(
+	resolveNamespace func(ctx context.Context) (string, error),
+	governanceService governance.Service,
+	options ...httptransport.HandlerOption,
+) Handler {
+	return &handler{
+		resolveNamespace:  resolveNamespace,
+		governanceService: governanceService,
+		options:           options,
+	}
+}

api/v3/handlers/governance/mapping.go

@@ -0,0 +1,109 @@
+package governance
+
+import (
+	"github.com/oapi-codegen/nullable"
+	"github.com/samber/lo"
+
+	apiv3 "github.com/openmeterio/openmeter/api/v3"
+	customershandler "github.com/openmeterio/openmeter/api/v3/handlers/customers"
+	"github.com/openmeterio/openmeter/openmeter/governance"
+)
+
+// ToAPIGovernanceQueryResponse maps a domain QueryResult to the API response.
+func ToAPIGovernanceQueryResponse(res governance.QueryResult, pageSize int) apiv3.GovernanceQueryResponse {
+	data := make([]apiv3.GovernanceQueryResult, 0, len(res.Customers))
+
+	for _, c := range res.Customers {
+		features := make(map[string]apiv3.GovernanceFeatureAccess, len(c.Features))
+		for key, fa := range c.Features {
+			features[key] = toAPIFeatureAccess(fa)
+		}
+
+		data = append(data, apiv3.GovernanceQueryResult{
+			Matched:   c.Matched,
+			Customer:  customershandler.ToAPIBillingCustomer(c.Customer),
+			Features:  features,
+			UpdatedAt: c.UpdatedAt,
+		})
+	}
+
+	errs := make([]apiv3.GovernanceQueryError, 0, len(res.Errors))
+
+	for _, e := range res.Errors {
+		errs = append(errs, apiv3.GovernanceQueryError{
+			Customer: lo.ToPtr(e.CustomerKey),
+			Code:     toAPIQueryErrorCode(e.Code),
+			Message:  e.Message,
+		})
+	}
+
+	return apiv3.GovernanceQueryResponse{
+		Data:   data,
+		Errors: errs,
+		Meta:   toAPICursorMeta(res, pageSize),
+	}
+}
+
+func toAPIFeatureAccess(fa governance.FeatureAccess) apiv3.GovernanceFeatureAccess {
+	out := apiv3.GovernanceFeatureAccess{HasAccess: fa.HasAccess}
+
+	if fa.Reason != nil {
+		out.Reason = &apiv3.GovernanceFeatureAccessReason{
+			Code:    toAPIReasonCode(fa.Reason.Code),
+			Message: fa.Reason.Message,
+		}
+	}
+
+	return out
+}
+
+func toAPIReasonCode(code governance.ReasonCode) apiv3.GovernanceFeatureAccessReasonCode {
+	switch code {
+	case governance.ReasonCodeUsageLimitReached:
+		return apiv3.GovernanceFeatureAccessReasonCodeUsageLimitReached
+	case governance.ReasonCodeFeatureUnavailable:
+		return apiv3.GovernanceFeatureAccessReasonCodeFeatureUnavailable
+	case governance.ReasonCodeFeatureNotFound:
+		return apiv3.GovernanceFeatureAccessReasonCodeFeatureNotFound
+	case governance.ReasonCodeNoCreditAvailable:
+		return apiv3.GovernanceFeatureAccessReasonCodeNoCreditAvailable
+	default:
+		return apiv3.GovernanceFeatureAccessReasonCodeUnknown
+	}
+}
+
+func toAPIQueryErrorCode(code governance.QueryErrorCode) apiv3.GovernanceQueryErrorCode {
+	switch code {
+	case governance.QueryErrorCustomerNotFound:
+		return apiv3.GovernanceQueryErrorCodeCustomerNotFound
+	default:
+		return apiv3.GovernanceQueryErrorCodeUnknown
+	}
+}
+
+// toAPICursorMeta builds cursor pagination metadata from the domain result.
+func toAPICursorMeta(res governance.QueryResult, pageSize int) apiv3.CursorMeta {
+	meta := apiv3.CursorMeta{
+		Page: apiv3.CursorMetaPage{
+			Next:     nullable.NewNullNullable[string](),
+			Previous: nullable.NewNullNullable[string](),
+			Size:     float32(pageSize),
+		},
+	}
+
+	if res.First != nil {
+		meta.Page.First = lo.ToPtr(res.First.Encode())
+		if res.HasPrev {
+			meta.Page.Previous = nullable.NewNullableWithValue(res.First.Encode())
+		}
+	}
+
+	if res.Last != nil {
+		meta.Page.Last = lo.ToPtr(res.Last.Encode())
+		if res.HasNext {
+			meta.Page.Next = nullable.NewNullableWithValue(res.Last.Encode())
+		}
+	}
+
+	return meta
+}

api/v3/handlers/governance/query.go

@@ -0,0 +1,141 @@
+package governance
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+
+	apiv3 "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/openmeter/governance"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+	pagination "github.com/openmeterio/openmeter/pkg/pagination/v2"
+)
+
+const (
+	defaultPageSize = 100
+	maxPageSize     = 100
+)
+
+type (
+	QueryGovernanceAccessParams   = apiv3.QueryGovernanceAccessParams
+	QueryGovernanceAccessRequest  = governance.QueryAccessInput
+	QueryGovernanceAccessResponse = apiv3.GovernanceQueryResponse
+	QueryGovernanceAccessHandler  = httptransport.HandlerWithArgs[QueryGovernanceAccessRequest, QueryGovernanceAccessResponse, QueryGovernanceAccessParams]
+)
+
+func (h *handler) QueryGovernanceAccess() QueryGovernanceAccessHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, params QueryGovernanceAccessParams) (QueryGovernanceAccessRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return QueryGovernanceAccessRequest{}, err
+			}
+
+			var body apiv3.GovernanceQueryRequest
+
+			if err := commonhttp.JSONRequestBodyDecoder(r, &body); err != nil {
+				return QueryGovernanceAccessRequest{}, err
+			}
+
+			req := QueryGovernanceAccessRequest{
+				Namespace:    ns,
+				CustomerKeys: body.Customer.Keys,
+				PageSize:     defaultPageSize,
+			}
+
+			if body.Feature != nil {
+				req.FeatureKeys = body.Feature.Keys
+			}
+
+			if body.IncludeCredits != nil {
+				req.IncludeCredits = *body.IncludeCredits
+			}
+
+			if err := applyPaging(ctx, &req, params); err != nil {
+				return QueryGovernanceAccessRequest{}, err
+			}
+
+			return req, nil
+		},
+		func(ctx context.Context, request QueryGovernanceAccessRequest) (QueryGovernanceAccessResponse, error) {
+			res, err := h.governanceService.QueryAccess(ctx, request)
+			if err != nil {
+				return QueryGovernanceAccessResponse{}, err
+			}
+
+			return ToAPIGovernanceQueryResponse(res, request.PageSize), nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[QueryGovernanceAccessResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("query-governance-access"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}
+
+// applyPaging parses page[size]/page[after]/page[before] into the service input.
+func applyPaging(ctx context.Context, req *QueryGovernanceAccessRequest, params QueryGovernanceAccessParams) error {
+	if params.Page == nil {
+		return nil
+	}
+
+	if params.Page.Size != nil {
+		if *params.Page.Size < 1 || *params.Page.Size > maxPageSize {
+			return apierrors.NewBadRequestError(ctx,
+				fmt.Errorf("page[size] must be between 1 and %d", maxPageSize),
+				apierrors.InvalidParameters{{
+					Field:  "page[size]",
+					Reason: fmt.Sprintf("must be between 1 and %d", maxPageSize),
+					Source: apierrors.InvalidParamSourceQuery,
+				}},
+			)
+		}
+
+		req.PageSize = *params.Page.Size
+	}
+
+	if params.Page.After != nil && params.Page.Before != nil {
+		return apierrors.NewBadRequestError(ctx,
+			fmt.Errorf("page[after] and page[before] are mutually exclusive"),
+			apierrors.InvalidParameters{{
+				Field:  "page[after]",
+				Reason: "cannot be combined with page[before]",
+				Source: apierrors.InvalidParamSourceQuery,
+			}},
+		)
+	}
+
+	if params.Page.After != nil {
+		cursor, err := decodeCursorParam(ctx, "page[after]", *params.Page.After)
+		if err != nil {
+			return err
+		}
+		req.After = cursor
+	}
+
+	if params.Page.Before != nil {
+		cursor, err := decodeCursorParam(ctx, "page[before]", *params.Page.Before)
+		if err != nil {
+			return err
+		}
+		req.Before = cursor
+	}
+
+	return nil
+}
+
+func decodeCursorParam(ctx context.Context, field, raw string) (*pagination.Cursor, error) {
+	cursor, err := pagination.DecodeCursor(raw)
+	if err != nil {
+		return nil, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{{
+			Field:  field,
+			Reason: err.Error(),
+			Source: apierrors.InvalidParamSourceQuery,
+		}})
+	}
+
+	return cursor, nil
+}

api/v3/handlers/llmcost/convert.go

@@ -0,0 +1,216 @@
+package llmcost
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"github.com/alpacahq/alpacadecimal"
+	"github.com/samber/lo"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/openmeter/llmcost"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+// providerDisplayNames maps canonical provider IDs to their formatted display names.
+var providerDisplayNames = map[string]string{
+	"amazon":    "Amazon",
+	"anthropic": "Anthropic",
+	"azure":     "Azure",
+	"bedrock":   "Amazon Bedrock",
+	"cohere":    "Cohere",
+	"deepseek":  "DeepSeek",
+	"google":    "Google",
+	"kilo":      "Kilo",
+	"meta":      "Meta",
+	"minimax":   "MiniMax",
+	"mistral":   "Mistral",
+	"nanogpt":   "NanoGPT",
+	"openai":    "OpenAI",
+	"vertex_ai": "Google Vertex AI",
+	"xai":       "xAI",
+}
+
+// formatProviderName returns the display name for a provider ID.
+// Known providers get their canonical display name; unknown providers
+// get their ID with the first letter capitalized.
+func formatProviderName(id string) string {
+	if name, ok := providerDisplayNames[strings.ToLower(id)]; ok {
+		return name
+	}
+
+	if id == "" {
+		return ""
+	}
+
+	// Fallback: split on hyphens/underscores, capitalize each word
+	words := strings.FieldsFunc(id, func(r rune) bool {
+		return r == '-' || r == '_'
+	})
+	for i, w := range words {
+		if len(w) > 0 {
+			words[i] = strings.ToUpper(w[:1]) + w[1:]
+		}
+	}
+
+	return strings.Join(words, " ")
+}
+
+func domainPriceToAPI(p llmcost.Price) api.LLMCostPrice {
+	// Map internal source to API source: manual stays manual, everything else is system.
+	source := api.LLMCostPriceSourceSystem
+	if p.Source == llmcost.PriceSourceManual {
+		source = api.LLMCostPriceSourceManual
+	}
+
+	providerID := string(p.Provider)
+
+	out := api.LLMCostPrice{
+		Id: p.ID,
+		Provider: api.LLMCostProvider{
+			Id:   providerID,
+			Name: formatProviderName(providerID),
+		},
+		Model: api.LLMCostModel{
+			Id:   p.ModelID,
+			Name: p.ModelName,
+		},
+		Currency:      p.Currency,
+		Source:        source,
+		EffectiveFrom: p.EffectiveFrom,
+		EffectiveTo:   p.EffectiveTo,
+		Pricing:       domainPricingToAPI(p.Pricing),
+	}
+
+	out.CreatedAt = p.CreatedAt
+	out.UpdatedAt = p.UpdatedAt
+
+	return out
+}
+
+func domainPricingToAPI(p llmcost.ModelPricing) api.LLMCostModelPricing {
+	out := api.LLMCostModelPricing{
+		InputPerToken:  p.InputPerToken.String(),
+		OutputPerToken: p.OutputPerToken.String(),
+	}
+
+	if p.CacheReadPerToken != nil {
+		out.CacheReadPerToken = lo.ToPtr(p.CacheReadPerToken.String())
+	}
+
+	if p.CacheWritePerToken != nil {
+		out.CacheWritePerToken = lo.ToPtr(p.CacheWritePerToken.String())
+	}
+
+	if p.ReasoningPerToken != nil {
+		out.ReasoningPerToken = lo.ToPtr(p.ReasoningPerToken.String())
+	}
+
+	return out
+}
+
+func apiPricingToDomain(p api.LLMCostModelPricing) (llmcost.ModelPricing, error) {
+	inputPerToken, err := decimalFromString(p.InputPerToken)
+	if err != nil {
+		return llmcost.ModelPricing{}, models.NewGenericValidationError(
+			fmt.Errorf("invalid input_per_token: %w", err),
+		)
+	}
+
+	outputPerToken, err := decimalFromString(p.OutputPerToken)
+	if err != nil {
+		return llmcost.ModelPricing{}, models.NewGenericValidationError(
+			fmt.Errorf("invalid output_per_token: %w", err),
+		)
+	}
+
+	out := llmcost.ModelPricing{
+		InputPerToken:  inputPerToken,
+		OutputPerToken: outputPerToken,
+	}
+
+	if p.CacheReadPerToken != nil {
+		d, err := decimalFromString(*p.CacheReadPerToken)
+		if err != nil {
+			return llmcost.ModelPricing{}, models.NewGenericValidationError(
+				fmt.Errorf("invalid cache_read_per_token: %w", err),
+			)
+		}
+		out.CacheReadPerToken = &d
+	}
+
+	if p.ReasoningPerToken != nil {
+		d, err := decimalFromString(*p.ReasoningPerToken)
+		if err != nil {
+			return llmcost.ModelPricing{}, models.NewGenericValidationError(
+				fmt.Errorf("invalid reasoning_per_token: %w", err),
+			)
+		}
+		out.ReasoningPerToken = &d
+	}
+
+	if p.CacheWritePerToken != nil {
+		d, err := decimalFromString(*p.CacheWritePerToken)
+		if err != nil {
+			return llmcost.ModelPricing{}, models.NewGenericValidationError(
+				fmt.Errorf("invalid cache_write_per_token: %w", err),
+			)
+		}
+		out.CacheWritePerToken = &d
+	}
+
+	return out, nil
+}
+
+func apiCreateOverrideToDomain(ns string, body api.LLMCostOverrideCreate) (llmcost.CreateOverrideInput, error) {
+	pricing, err := apiPricingToDomain(body.Pricing)
+	if err != nil {
+		return llmcost.CreateOverrideInput{}, err
+	}
+
+	input := llmcost.CreateOverrideInput{
+		Namespace:     ns,
+		Provider:      llmcost.Provider(body.Provider),
+		ModelID:       body.ModelId,
+		Pricing:       pricing,
+		Currency:      body.Currency,
+		EffectiveFrom: body.EffectiveFrom,
+	}
+
+	if body.ModelName != nil {
+		input.ModelName = *body.ModelName
+	}
+
+	if body.EffectiveTo != nil {
+		input.EffectiveTo = body.EffectiveTo
+	}
+
+	return input, nil
+}
+
+func decimalFromString(s string) (alpacadecimal.Decimal, error) {
+	v, err := alpacadecimal.NewFromString(s)
+	if err != nil {
+		return alpacadecimal.Decimal{}, models.NewGenericValidationError(
+			fmt.Errorf("invalid decimal: %w", err),
+		)
+	}
+
+	return v, nil
+}
+
+// FromAPILlmCostSortField validates a v3 (snake_case) LLM cost price sort field,
+// returning it unchanged because the price adapter matches these wire strings
+// directly. Returns a 400 for any unsupported field.
+func FromAPILlmCostSortField(ctx context.Context, field string) (string, error) {
+	switch field {
+	case "id", "provider.id", "model.id", "effective_from", "effective_to":
+		return field, nil
+	default:
+		return "", apierrors.NewUnsupportedSortFieldError(
+			ctx, field, "id", "provider.id", "model.id", "effective_from", "effective_to",
+		)
+	}
+}

api/v3/handlers/llmcost/convert_test.go

@@ -0,0 +1,22 @@
+package llmcost
+
+import (
+	"testing"
+
+	"github.com/samber/lo"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+)
+
+func TestFilterSourceInListPricesParams(t *testing.T) {
+	// Compile-time assertion that the generated API type includes the Source field.
+	filter := &api.ListLLMCostPricesParamsFilter{
+		Source: &api.StringFieldFilter{
+			Eq: lo.ToPtr("system"),
+		},
+	}
+	require.NotNil(t, filter.Source)
+	assert.Equal(t, lo.ToPtr("system"), filter.Source.Eq)
+}

api/v3/handlers/llmcost/create_override.go

@@ -0,0 +1,52 @@
+package llmcost
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/api/v3/request"
+	"github.com/openmeterio/openmeter/openmeter/llmcost"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type (
+	CreateOverrideRequest  = llmcost.CreateOverrideInput
+	CreateOverrideResponse = api.LLMCostPrice
+	CreateOverrideHandler  = httptransport.Handler[CreateOverrideRequest, CreateOverrideResponse]
+)
+
+func (h *handler) CreateOverride() CreateOverrideHandler {
+	return httptransport.NewHandler(
+		func(ctx context.Context, r *http.Request) (CreateOverrideRequest, error) {
+			var body api.LLMCostOverrideCreate
+			if err := request.ParseBody(r, &body); err != nil {
+				return CreateOverrideRequest{}, err
+			}
+
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return CreateOverrideRequest{}, err
+			}
+
+			return apiCreateOverrideToDomain(ns, body)
+		},
+		func(ctx context.Context, req CreateOverrideRequest) (CreateOverrideResponse, error) {
+			price, err := h.service.CreateOverride(ctx, req)
+			if err != nil {
+				return CreateOverrideResponse{}, fmt.Errorf("failed to create llm cost override: %w", err)
+			}
+
+			return domainPriceToAPI(price), nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[CreateOverrideResponse](http.StatusCreated),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("create-llm-cost-override"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/llmcost/delete_override.go

@@ -0,0 +1,48 @@
+package llmcost
+
+import (
+	"context"
+	"net/http"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/openmeter/llmcost"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type (
+	DeleteOverrideRequest  = llmcost.DeleteOverrideInput
+	DeleteOverrideResponse = interface{}
+	DeleteOverrideHandler  = httptransport.HandlerWithArgs[DeleteOverrideRequest, DeleteOverrideResponse, api.ULID]
+)
+
+func (h *handler) DeleteOverride() DeleteOverrideHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, overrideID api.ULID) (DeleteOverrideRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return DeleteOverrideRequest{}, err
+			}
+
+			return DeleteOverrideRequest{
+				ID:        overrideID,
+				Namespace: ns,
+			}, nil
+		},
+		func(ctx context.Context, req DeleteOverrideRequest) (DeleteOverrideResponse, error) {
+			err := h.service.DeleteOverride(ctx, req)
+			if err != nil {
+				return nil, err
+			}
+
+			return nil, nil
+		},
+		commonhttp.EmptyResponseEncoder[DeleteOverrideResponse](http.StatusNoContent),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("delete-llm-cost-override"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/llmcost/get_price.go

@@ -0,0 +1,48 @@
+package llmcost
+
+import (
+	"context"
+	"net/http"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/openmeter/llmcost"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type (
+	GetPriceRequest  = llmcost.GetPriceInput
+	GetPriceResponse = api.LLMCostPrice
+	GetPriceHandler  = httptransport.HandlerWithArgs[GetPriceRequest, GetPriceResponse, api.ULID]
+)
+
+func (h *handler) GetPrice() GetPriceHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, priceID api.ULID) (GetPriceRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return GetPriceRequest{}, err
+			}
+
+			return GetPriceRequest{
+				ID:        priceID,
+				Namespace: ns,
+			}, nil
+		},
+		func(ctx context.Context, request GetPriceRequest) (GetPriceResponse, error) {
+			price, err := h.service.GetPrice(ctx, request)
+			if err != nil {
+				return GetPriceResponse{}, err
+			}
+
+			return domainPriceToAPI(price), nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[GetPriceResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("get-llm-cost-price"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/llmcost/handler.go

@@ -0,0 +1,34 @@
+package llmcost
+
+import (
+	"context"
+
+	"github.com/openmeterio/openmeter/openmeter/llmcost"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type Handler interface {
+	ListPrices() ListPricesHandler
+	GetPrice() GetPriceHandler
+	ListOverrides() ListOverridesHandler
+	CreateOverride() CreateOverrideHandler
+	DeleteOverride() DeleteOverrideHandler
+}
+
+type handler struct {
+	resolveNamespace func(ctx context.Context) (string, error)
+	service          llmcost.Service
+	options          []httptransport.HandlerOption
+}
+
+func New(
+	resolveNamespace func(ctx context.Context) (string, error),
+	service llmcost.Service,
+	options ...httptransport.HandlerOption,
+) Handler {
+	return &handler{
+		resolveNamespace: resolveNamespace,
+		service:          service,
+		options:          options,
+	}
+}

api/v3/handlers/llmcost/list_overrides.go

@@ -0,0 +1,112 @@
+package llmcost
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+
+	"github.com/samber/lo"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/api/v3/filters"
+	"github.com/openmeterio/openmeter/api/v3/response"
+	"github.com/openmeterio/openmeter/openmeter/llmcost"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+)
+
+type (
+	ListOverridesRequest  = llmcost.ListOverridesInput
+	ListOverridesResponse = response.PagePaginationResponse[api.LLMCostPrice]
+	ListOverridesParams   = api.ListLlmCostOverridesParams
+	ListOverridesHandler  = httptransport.HandlerWithArgs[ListOverridesRequest, ListOverridesResponse, ListOverridesParams]
+)
+
+func (h *handler) ListOverrides() ListOverridesHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, params ListOverridesParams) (ListOverridesRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return ListOverridesRequest{}, err
+			}
+
+			req := ListOverridesRequest{
+				Namespace: ns,
+			}
+
+			// Pagination
+			req.Page = pagination.NewPage(1, 20)
+
+			if params.Page != nil {
+				req.Page = pagination.NewPage(
+					lo.FromPtrOr(params.Page.Number, 1),
+					lo.FromPtrOr(params.Page.Size, 20),
+				)
+
+				if err := req.Page.Validate(); err != nil {
+					return req, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "page", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+			}
+
+			// Filters
+			if params.Filter != nil {
+				provider, err := filters.FromAPIFilterString(params.Filter.Provider)
+				if err != nil {
+					return ListOverridesRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[provider]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.Provider = provider
+				modelID, err := filters.FromAPIFilterString(params.Filter.ModelId)
+				if err != nil {
+					return ListOverridesRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[model_id]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.ModelID = modelID
+				modelName, err := filters.FromAPIFilterString(params.Filter.ModelName)
+				if err != nil {
+					return ListOverridesRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[model_name]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.ModelName = modelName
+				currency, err := filters.FromAPIFilterString(params.Filter.Currency)
+				if err != nil {
+					return ListOverridesRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[currency]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.Currency = currency
+			}
+
+			return req, nil
+		},
+		func(ctx context.Context, request ListOverridesRequest) (ListOverridesResponse, error) {
+			result, err := h.service.ListOverrides(ctx, request)
+			if err != nil {
+				return ListOverridesResponse{}, fmt.Errorf("failed to list llm cost overrides: %w", err)
+			}
+
+			items := lo.Map(result.Items, func(item llmcost.Price, _ int) api.LLMCostPrice {
+				return domainPriceToAPI(item)
+			})
+
+			return response.NewPagePaginationResponse(items, response.PageMetaPage{
+				Size:   request.Page.PageSize,
+				Number: request.Page.PageNumber,
+				Total:  lo.ToPtr(result.TotalCount),
+			}), nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[ListOverridesResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("list-llm-cost-overrides"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/llmcost/list_prices.go

@@ -0,0 +1,138 @@
+package llmcost
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+
+	"github.com/samber/lo"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/api/v3/filters"
+	"github.com/openmeterio/openmeter/api/v3/request"
+	"github.com/openmeterio/openmeter/api/v3/response"
+	"github.com/openmeterio/openmeter/openmeter/llmcost"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+)
+
+type (
+	ListPricesRequest  = llmcost.ListPricesInput
+	ListPricesResponse = response.PagePaginationResponse[api.LLMCostPrice]
+	ListPricesParams   = api.ListLlmCostPricesParams
+	ListPricesHandler  = httptransport.HandlerWithArgs[ListPricesRequest, ListPricesResponse, ListPricesParams]
+)
+
+func (h *handler) ListPrices() ListPricesHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, params ListPricesParams) (ListPricesRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return ListPricesRequest{}, err
+			}
+
+			req := ListPricesRequest{
+				Namespace: ns,
+			}
+
+			// Pagination
+			req.Page = pagination.NewPage(1, 20)
+
+			if params.Page != nil {
+				req.Page = pagination.NewPage(
+					lo.FromPtrOr(params.Page.Number, 1),
+					lo.FromPtrOr(params.Page.Size, 20),
+				)
+
+				if err := req.Page.Validate(); err != nil {
+					return req, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "page", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+			}
+
+			// Sort
+			if params.Sort != nil {
+				sort, err := request.ParseSortBy(*params.Sort)
+				if err != nil {
+					return req, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "sort", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+
+				orderBy, err := FromAPILlmCostSortField(ctx, sort.Field)
+				if err != nil {
+					return req, err
+				}
+
+				req.OrderBy = orderBy
+				req.Order = sort.Order.ToSortxOrder()
+			}
+
+			// Filters
+			if params.Filter != nil {
+				provider, err := filters.FromAPIFilterString(params.Filter.Provider)
+				if err != nil {
+					return ListPricesRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[provider]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.Provider = provider
+				modelID, err := filters.FromAPIFilterString(params.Filter.ModelId)
+				if err != nil {
+					return ListPricesRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[model_id]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.ModelID = modelID
+				modelName, err := filters.FromAPIFilterString(params.Filter.ModelName)
+				if err != nil {
+					return ListPricesRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[model_name]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.ModelName = modelName
+				currency, err := filters.FromAPIFilterString(params.Filter.Currency)
+				if err != nil {
+					return ListPricesRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[currency]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.Currency = currency
+				source, err := filters.FromAPIFilterString(params.Filter.Source)
+				if err != nil {
+					return ListPricesRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[source]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.Source = source
+			}
+
+			return req, nil
+		},
+		func(ctx context.Context, request ListPricesRequest) (ListPricesResponse, error) {
+			result, err := h.service.ListPrices(ctx, request)
+			if err != nil {
+				return ListPricesResponse{}, fmt.Errorf("failed to list llm cost prices: %w", err)
+			}
+
+			items := lo.Map(result.Items, func(item llmcost.Price, _ int) api.LLMCostPrice {
+				return domainPriceToAPI(item)
+			})
+
+			return response.NewPagePaginationResponse(items, response.PageMetaPage{
+				Size:   request.Page.PageSize,
+				Number: request.Page.PageNumber,
+				Total:  lo.ToPtr(result.TotalCount),
+			}), nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[ListPricesResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("list-llm-cost-prices"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/meters/convert.gen.go

@@ -0,0 +1,79 @@
+// Code generated by github.com/jmattheis/goverter, DO NOT EDIT.
+//go:build !goverter
+
+package meters
+
+import (
+	v3 "github.com/openmeterio/openmeter/api/v3"
+	response "github.com/openmeterio/openmeter/api/v3/response"
+	meter "github.com/openmeterio/openmeter/openmeter/meter"
+	"time"
+)
+
+func init() {
+	FromAPICreateMeterRequest = func(context string, source v3.CreateMeterRequest) (meter.CreateMeterInput, error) {
+		var meterCreateMeterInput meter.CreateMeterInput
+		meterCreateMeterInput.Namespace = NamespaceFromContext(context)
+		meterCreateMeterInput.Name = source.Name
+		meterCreateMeterInput.Key = source.Key
+		meterCreateMeterInput.Description = source.Description
+		meterCreateMeterInput.Aggregation = FromAPIMeterAggregation(source.Aggregation)
+		meterCreateMeterInput.EventType = source.EventType
+		meterCreateMeterInput.EventFrom = source.EventsFrom
+		meterCreateMeterInput.ValueProperty = source.ValueProperty
+		if source.Dimensions != nil {
+			meterCreateMeterInput.GroupBy = (*source.Dimensions)
+		}
+		modelsMetadata, err := ConvertLabelsToMetadata(source.Labels)
+		if err != nil {
+			return meterCreateMeterInput, err
+		}
+		meterCreateMeterInput.Metadata = modelsMetadata
+		return meterCreateMeterInput, nil
+	}
+	ToAPIMeter = func(source meter.Meter) v3.Meter {
+		var v3Meter v3.Meter
+		v3Meter.Aggregation = ToAPIMeterAggregation(source.Aggregation)
+		v3Meter.CreatedAt = timeTimeToTimeTime(source.ManagedResource.ManagedModel.CreatedAt)
+		v3Meter.DeletedAt = source.ManagedResource.ManagedModel.DeletedAt
+		v3Meter.Description = source.ManagedResource.Description
+		v3Meter.Dimensions = &source.GroupBy
+		v3Meter.EventType = source.EventType
+		v3Meter.EventsFrom = source.EventFrom
+		v3Meter.Id = source.ManagedResource.ID
+		v3Meter.Key = source.Key
+		v3Meter.Labels = ConvertMetadataAnnotationsToLabels(source)
+		v3Meter.Name = source.ManagedResource.Name
+		v3Meter.UpdatedAt = timeTimeToTimeTime(source.ManagedResource.ManagedModel.UpdatedAt)
+		v3Meter.ValueProperty = source.ValueProperty
+		return v3Meter
+	}
+	ToAPIMeterPagePaginatedResponse = func(source response.PagePaginationResponse[meter.Meter]) v3.MeterPagePaginatedResponse {
+		var v3MeterPagePaginatedResponse v3.MeterPagePaginatedResponse
+		if source.Data != nil {
+			v3MeterPagePaginatedResponse.Data = make([]v3.Meter, len(source.Data))
+			for i := 0; i < len(source.Data); i++ {
+				v3MeterPagePaginatedResponse.Data[i] = ToAPIMeter(source.Data[i])
+			}
+		}
+		v3MeterPagePaginatedResponse.Meta = responsePageMetaToV3PaginatedMeta(source.Meta)
+		return v3MeterPagePaginatedResponse
+	}
+}
+func responsePageMetaPageToV3PageMeta(source response.PageMetaPage) v3.PageMeta {
+	var v3PageMeta v3.PageMeta
+	v3PageMeta.Number = IntToFloat32(source.Number)
+	v3PageMeta.Size = IntToFloat32(source.Size)
+	if source.Total != nil {
+		v3PageMeta.Total = IntToFloat32(*source.Total)
+	}
+	return v3PageMeta
+}
+func responsePageMetaToV3PaginatedMeta(source response.PageMeta) v3.PaginatedMeta {
+	var v3PaginatedMeta v3.PaginatedMeta
+	v3PaginatedMeta.Page = responsePageMetaPageToV3PageMeta(source.Page)
+	return v3PaginatedMeta
+}
+func timeTimeToTimeTime(source time.Time) time.Time {
+	return source
+}

api/v3/handlers/meters/convert.go

@@ -0,0 +1,204 @@
+//go:generate go run github.com/jmattheis/goverter/cmd/goverter gen ./
+package meters
+
+import (
+	"context"
+
+	"github.com/alpacahq/alpacadecimal"
+	"github.com/samber/lo"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/api/v3/handlers/meters/query"
+	"github.com/openmeterio/openmeter/api/v3/labels"
+	"github.com/openmeterio/openmeter/api/v3/response"
+	"github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+// goverter:variables
+// goverter:skipCopySameType
+// goverter:output:file ./convert.gen.go
+// goverter:useZeroValueOnPointerInconsistency
+// goverter:useUnderlyingTypeMethods
+// goverter:matchIgnoreCase
+// goverter:extend FromAPIMeterAggregation
+// goverter:extend ToAPIMeterAggregation
+// goverter:extend ConvertMetadataAnnotationsToLabels
+// goverter:extend ConvertLabelsToMetadata
+// goverter:extend IntToFloat32
+var (
+	// goverter:context namespace
+	// goverter:map Namespace | NamespaceFromContext
+	// goverter:map Dimensions GroupBy
+	// goverter:map Labels Metadata
+	// goverter:map EventsFrom EventFrom
+	// goverter:ignore Annotations
+	// goverter:ignore inputOptions
+	FromAPICreateMeterRequest func(namespace string, createMeterRequest api.CreateMeterRequest) (meter.CreateMeterInput, error)
+	// goverter:map GroupBy Dimensions
+	// goverter:map EventFrom EventsFrom
+	// goverter:map ManagedResource.ID Id
+	// goverter:map ManagedResource.Description Description
+	// goverter:map ManagedResource.Name Name
+	// goverter:map ManagedResource.ManagedModel.CreatedAt CreatedAt
+	// goverter:map ManagedResource.ManagedModel.UpdatedAt UpdatedAt
+	// goverter:map ManagedResource.ManagedModel.DeletedAt DeletedAt
+	// goverter:map . Labels | ConvertMetadataAnnotationsToLabels
+	ToAPIMeter                      func(meter.Meter) api.Meter
+	ToAPIMeterPagePaginatedResponse func(meters response.PagePaginationResponse[meter.Meter]) api.MeterPagePaginatedResponse
+)
+
+var ConvertLabelsToMetadata = labels.ToMetadata
+
+func ConvertMetadataAnnotationsToLabels(source meter.Meter) *api.Labels {
+	return labels.FromMetadataAnnotations(source.Metadata, source.Annotations)
+}
+
+//goverter:context namespace
+func NamespaceFromContext(namespace string) string {
+	return namespace
+}
+
+func ToAPIMeterAggregation(aggregation meter.MeterAggregation) api.MeterAggregation {
+	switch aggregation {
+	case meter.MeterAggregationSum:
+		return api.MeterAggregationSum
+	case meter.MeterAggregationCount:
+		return api.MeterAggregationCount
+	case meter.MeterAggregationUniqueCount:
+		return api.MeterAggregationUniqueCount
+	case meter.MeterAggregationAvg:
+		return api.MeterAggregationAvg
+	case meter.MeterAggregationMin:
+		return api.MeterAggregationMin
+	case meter.MeterAggregationMax:
+		return api.MeterAggregationMax
+	case meter.MeterAggregationLatest:
+		return api.MeterAggregationLatest
+	}
+
+	return api.MeterAggregation("")
+}
+
+func FromAPIMeterAggregation(aggregation api.MeterAggregation) meter.MeterAggregation {
+	switch aggregation {
+	case api.MeterAggregationSum:
+		return meter.MeterAggregationSum
+	case api.MeterAggregationCount:
+		return meter.MeterAggregationCount
+	case api.MeterAggregationUniqueCount:
+		return meter.MeterAggregationUniqueCount
+	case api.MeterAggregationAvg:
+		return meter.MeterAggregationAvg
+	case api.MeterAggregationMin:
+		return meter.MeterAggregationMin
+	case api.MeterAggregationMax:
+		return meter.MeterAggregationMax
+	case api.MeterAggregationLatest:
+		return meter.MeterAggregationLatest
+	}
+
+	return ""
+}
+
+func IntToFloat32(i int) float32 {
+	return float32(i)
+}
+
+func FromAPIUpdateMeterRequest(namespace string, meterID string, body api.UpdateMeterRequest) (meter.UpdateMeterInput, error) {
+	input := meter.UpdateMeterInput{
+		ID: models.NamespacedID{
+			Namespace: namespace,
+			ID:        meterID,
+		},
+	}
+
+	if body.Name != nil {
+		input.Name = *body.Name
+	}
+
+	input.Description = body.Description
+
+	if body.Dimensions != nil {
+		input.GroupBy = *body.Dimensions
+	}
+
+	if body.Labels != nil {
+		metadata, err := labels.ToMetadata(body.Labels)
+		if err != nil {
+			return meter.UpdateMeterInput{}, err
+		}
+
+		input.Metadata = metadata
+	}
+
+	return input, nil
+}
+
+// ConvertMetadataToLabels converts models.Metadata to api.Labels.
+// Always returns an initialized map (never nil) so JSON serializes to {} instead of null.
+func ConvertMetadataToLabels(source models.Metadata) *api.Labels {
+	labels := make(api.Labels)
+	for k, v := range source {
+		labels[k] = v
+	}
+	return &labels
+}
+
+func ToAPIMeterQueryRow(row meter.MeterQueryRow) api.MeterQueryRow {
+	dimensions := make(map[string]string)
+
+	if row.Subject != nil {
+		dimensions[query.DimensionSubject] = *row.Subject
+	}
+
+	if row.CustomerID != nil {
+		dimensions[query.DimensionCustomerID] = *row.CustomerID
+	}
+
+	for key, value := range row.GroupBy {
+		if key == query.DimensionSubject || key == query.DimensionCustomerID {
+			continue
+		}
+		if value != nil {
+			dimensions[key] = *value
+		}
+	}
+
+	return api.MeterQueryRow{
+		Value:      alpacadecimal.NewFromFloat(row.Value).String(),
+		From:       row.WindowStart,
+		To:         row.WindowEnd,
+		Dimensions: dimensions,
+	}
+}
+
+func ToAPIMeterQueryResult(from *api.DateTime, to *api.DateTime, rows []meter.MeterQueryRow) api.MeterQueryResult {
+	return api.MeterQueryResult{
+		From: from,
+		To:   to,
+		Data: lo.Map(rows, func(row meter.MeterQueryRow, _ int) api.MeterQueryRow {
+			return ToAPIMeterQueryRow(row)
+		}),
+	}
+}
+
+func FromAPIMeterSortField(ctx context.Context, field string) (meter.OrderBy, error) {
+	switch field {
+	case "key":
+		return meter.OrderByKey, nil
+	case "name":
+		return meter.OrderByName, nil
+	case "aggregation":
+		return meter.OrderByAggregation, nil
+	case "created_at":
+		return meter.OrderByCreatedAt, nil
+	case "updated_at":
+		return meter.OrderByUpdatedAt, nil
+	default:
+		return "", apierrors.NewUnsupportedSortFieldError(
+			ctx, field, "key", "name", "aggregation", "created_at", "updated_at",
+		)
+	}
+}

api/v3/handlers/meters/create.go

@@ -0,0 +1,58 @@
+package meters
+
+import (
+	"context"
+	"net/http"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/api/v3/request"
+	"github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type (
+	CreateMeterRequest  = meter.CreateMeterInput
+	CreateMeterResponse = api.Meter
+	CreateMeterHandler  httptransport.Handler[CreateMeterRequest, CreateMeterResponse]
+)
+
+// CreateMeter returns a new httptransport.Handler for creating a meter.
+func (h *handler) CreateMeter() CreateMeterHandler {
+	return httptransport.NewHandler(
+		func(ctx context.Context, r *http.Request) (CreateMeterRequest, error) {
+			body := api.CreateMeterRequest{}
+			if err := request.ParseBody(r, &body); err != nil {
+				return CreateMeterRequest{}, err
+			}
+
+			if body.Dimensions != nil {
+				if err := validateDimensionsWithoutReserved(*body.Dimensions); err != nil {
+					return CreateMeterRequest{}, err
+				}
+			}
+
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return CreateMeterRequest{}, err
+			}
+
+			return FromAPICreateMeterRequest(ns, body)
+		},
+		func(ctx context.Context, request CreateMeterRequest) (CreateMeterResponse, error) {
+			m, err := h.service.CreateMeter(ctx, request)
+			if err != nil {
+				return CreateMeterResponse{}, err
+			}
+
+			return ToAPIMeter(m), nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[CreateMeterResponse](http.StatusCreated),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("create-meter"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/meters/delete.go

@@ -0,0 +1,56 @@
+package meters
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	meter "github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type (
+	DeleteMeterRequest struct {
+		Namespace string
+		IDOrSlug  string
+	}
+	DeleteMeterResponse = interface{}
+	DeleteMeterParams   = string
+	DeleteMeterHandler  httptransport.HandlerWithArgs[DeleteMeterRequest, DeleteMeterResponse, DeleteMeterParams]
+)
+
+// DeleteMeter returns a handler for deleting a meter.
+func (h *handler) DeleteMeter() DeleteMeterHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, meterID DeleteMeterParams) (DeleteMeterRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return DeleteMeterRequest{}, err
+			}
+
+			return DeleteMeterRequest{
+				Namespace: ns,
+				IDOrSlug:  meterID,
+			}, nil
+		},
+		func(ctx context.Context, request DeleteMeterRequest) (DeleteMeterResponse, error) {
+			// FIXME: make delete idempotent, return 204 for repeated deletion
+			err := h.service.DeleteMeter(ctx, meter.DeleteMeterInput{
+				Namespace: request.Namespace,
+				IDOrSlug:  request.IDOrSlug,
+			})
+			if err != nil {
+				return nil, err
+			}
+
+			return nil, nil
+		},
+		commonhttp.EmptyResponseEncoder[DeleteMeterResponse](http.StatusNoContent),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("delete-meter"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/meters/dimensions.go

@@ -0,0 +1,13 @@
+package meters
+
+import "github.com/openmeterio/openmeter/api/v3/handlers/meters/query"
+
+func validateDimensionsWithoutReserved[T any](dimensions map[string]T) error {
+	for dimension := range dimensions {
+		if query.IsReservedDimension(dimension) {
+			return NewReservedDimensionError(dimension)
+		}
+	}
+
+	return nil
+}

api/v3/handlers/meters/errors.go

@@ -0,0 +1,22 @@
+package meters
+
+import (
+	"net/http"
+
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+const ErrCodeReservedDimension models.ErrorCode = "reserved_dimension"
+
+var ErrReservedDimension = models.NewValidationIssue(
+	ErrCodeReservedDimension,
+	"dimension name is reserved",
+	models.WithFieldString("dimensions"),
+	models.WithCriticalSeverity(),
+	commonhttp.WithHTTPStatusCodeAttribute(http.StatusBadRequest),
+)
+
+func NewReservedDimensionError(dimension string) error {
+	return ErrReservedDimension.WithPathString("dimensions", dimension).WithAttr("value", dimension)
+}

api/v3/handlers/meters/get.go

@@ -0,0 +1,51 @@
+package meters
+
+import (
+	"context"
+	"net/http"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type (
+	GetMeterRequest  = meter.GetMeterInput
+	GetMeterResponse = api.Meter
+	GetMeterParams   = string
+	GetMeterHandler  httptransport.HandlerWithArgs[GetMeterRequest, GetMeterResponse, GetMeterParams]
+)
+
+// GetMeter returns a handler for getting a meter.
+func (h *handler) GetMeter() GetMeterHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, meterID GetMeterParams) (GetMeterRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return GetMeterRequest{}, err
+			}
+
+			return GetMeterRequest{
+				Namespace: ns,
+				IDOrSlug:  meterID,
+			}, nil
+		},
+		func(ctx context.Context, request GetMeterRequest) (GetMeterResponse, error) {
+			// Get the meter
+			m, err := h.service.GetMeterByIDOrSlug(ctx, request)
+			if err != nil {
+				return GetMeterResponse{}, err
+			}
+
+			return ToAPIMeter(m), nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[GetMeterResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("get-meter"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}

api/v3/handlers/meters/handler.go

@@ -0,0 +1,44 @@
+package meters
+
+import (
+	"context"
+
+	"github.com/openmeterio/openmeter/openmeter/customer"
+	"github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/openmeter/streaming"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+)
+
+type Handler interface {
+	ListMeters() ListMetersHandler
+	GetMeter() GetMeterHandler
+	CreateMeter() CreateMeterHandler
+	UpdateMeter() UpdateMeterHandler
+	DeleteMeter() DeleteMeterHandler
+	QueryMeter() QueryMeterHandler
+	QueryMeterCSV() QueryMeterCSVHandler
+}
+
+type handler struct {
+	resolveNamespace func(ctx context.Context) (string, error)
+	service          meter.ManageService
+	streaming        streaming.Connector
+	customerService  customer.Service
+	options          []httptransport.HandlerOption
+}
+
+func New(
+	resolveNamespace func(ctx context.Context) (string, error),
+	service meter.ManageService,
+	streaming streaming.Connector,
+	customerService customer.Service,
+	options ...httptransport.HandlerOption,
+) Handler {
+	return &handler{
+		resolveNamespace: resolveNamespace,
+		service:          service,
+		streaming:        streaming,
+		customerService:  customerService,
+		options:          options,
+	}
+}

api/v3/handlers/meters/list.go

@@ -0,0 +1,118 @@
+package meters
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/samber/lo"
+
+	api "github.com/openmeterio/openmeter/api/v3"
+	"github.com/openmeterio/openmeter/api/v3/apierrors"
+	"github.com/openmeterio/openmeter/api/v3/filters"
+	"github.com/openmeterio/openmeter/api/v3/request"
+	"github.com/openmeterio/openmeter/api/v3/response"
+	"github.com/openmeterio/openmeter/openmeter/meter"
+	"github.com/openmeterio/openmeter/pkg/framework/commonhttp"
+	"github.com/openmeterio/openmeter/pkg/framework/transport/httptransport"
+	"github.com/openmeterio/openmeter/pkg/pagination"
+)
+
+type (
+	ListMetersRequest  = meter.ListMetersParams
+	ListMetersResponse = response.PagePaginationResponse[api.Meter]
+	ListMetersParams   = api.ListMetersParams
+	ListMetersHandler  httptransport.HandlerWithArgs[ListMetersRequest, ListMetersResponse, ListMetersParams]
+)
+
+func (h *handler) ListMeters() ListMetersHandler {
+	return httptransport.NewHandlerWithArgs(
+		func(ctx context.Context, r *http.Request, params ListMetersParams) (ListMetersRequest, error) {
+			ns, err := h.resolveNamespace(ctx)
+			if err != nil {
+				return ListMetersRequest{}, err
+			}
+
+			page := pagination.NewPage(1, 20)
+			if params.Page != nil {
+				page = pagination.NewPage(
+					lo.FromPtrOr(params.Page.Number, 1),
+					lo.FromPtrOr(params.Page.Size, 20),
+				)
+			}
+
+			if err := page.Validate(); err != nil {
+				return ListMetersRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+					apierrors.InvalidParameter{
+						Field:  "page",
+						Reason: err.Error(),
+						Source: apierrors.InvalidParamSourceQuery,
+					},
+				})
+			}
+
+			req := ListMetersRequest{
+				Namespace: ns,
+				Page:      page,
+			}
+
+			if params.Filter != nil {
+				key, err := filters.FromAPIFilterString(params.Filter.Key)
+				if err != nil {
+					return ListMetersRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[key]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.Key = key
+
+				name, err := filters.FromAPIFilterString(params.Filter.Name)
+				if err != nil {
+					return ListMetersRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "filter[name]", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				req.Name = name
+			}
+
+			if params.Sort != nil {
+				sort, err := request.ParseSortBy(*params.Sort)
+				if err != nil {
+					return ListMetersRequest{}, apierrors.NewBadRequestError(ctx, err, apierrors.InvalidParameters{
+						{Field: "sort", Reason: err.Error(), Source: apierrors.InvalidParamSourceQuery},
+					})
+				}
+				orderBy, err := FromAPIMeterSortField(ctx, sort.Field)
+				if err != nil {
+					return ListMetersRequest{}, err
+				}
+				req.OrderBy = orderBy
+				req.Order = sort.Order.ToSortxOrder()
+			}
+
+			return req, nil
+		},
+		func(ctx context.Context, request ListMetersRequest) (ListMetersResponse, error) {
+			resp, err := h.service.ListMeters(ctx, request)
+			if err != nil {
+				return ListMetersResponse{}, err
+			}
+
+			items := lo.Map(resp.Items, func(item meter.Meter, _ int) api.Meter {
+				return ToAPIMeter(item)
+			})
+
+			r := response.NewPagePaginationResponse(items, response.PageMetaPage{
+				Size:   request.Page.PageSize,
+				Number: request.Page.PageNumber,
+				Total:  lo.ToPtr(resp.TotalCount),
+			})
+
+			return r, nil
+		},
+		commonhttp.JSONResponseEncoderWithStatus[ListMetersResponse](http.StatusOK),
+		httptransport.AppendOptions(
+			h.options,
+			httptransport.WithOperationName("list-meters"),
+			httptransport.WithErrorEncoder(apierrors.GenericErrorEncoder()),
+		)...,
+	)
+}