fix: grants service should not bypass charges service for now

Author: turip

.agents/skills/charges/SKILL.md

@@ -214,6 +214,24 @@ Current expected behavior:
 - ledger handlers may still defensively tolerate zero and return `ledgertransaction.GroupReference{}`
 - when a service proceeds with non-zero invoice accrual, it must require a non-empty transaction group reference before storing accrued usage
 
+## HTTP/API Conversion
+
+Credit-purchase charges have an API/domain enum mismatch for promotional grants.
+
+Rules:
+
+- in the billing domain, promotional credit grants are represented as `creditpurchase.SettlementTypePromotional`
+- in the v3 customer credits API, the same case is represented as `funding_method=none`
+- v3 API responses for promotional grants must omit the `purchase` block entirely
+- conversion code in `api/v3/handlers/customers/credits` must map this case explicitly instead of treating `promotional` as an unsupported settlement type
+
+Important files:
+
+- `api/v3/handlers/customers/credits/convert.go`
+- `openmeter/billing/charges/creditpurchase/settlement.go`
+- `openmeter/billing/creditgrant/service/service.go`
+- `api/spec/packages/aip/src/customers/credits/grant.tsp`
+
 ## Realization Helper Subpackages
 
 Use small type-specific realization helper subpackages to keep charge services and state machines from becoming kitchen-sink orchestration layers.

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

@@ -142,6 +142,9 @@ func toAPICreditGrantPurchase(charge creditpurchase.Charge) (*creditGrantPurchas
 			SettlementStatus:   &settlementStatus,
 		}, nil
 
+	case creditpurchase.SettlementTypePromotional:
+		return nil, nil
+
 	default:
 		return nil, fmt.Errorf("invalid settlement type: %s", settlement.Type())
 	}

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

@@ -0,0 +1,50 @@
+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/billing/charges/creditpurchase"
+	"github.com/openmeterio/openmeter/openmeter/billing/charges/meta"
+	"github.com/openmeterio/openmeter/pkg/currencyx"
+	"github.com/openmeterio/openmeter/pkg/models"
+)
+
+func TestToAPIBillingCreditGrantPromotional(t *testing.T) {
+	now := time.Date(2026, time.April, 17, 10, 0, 0, 0, time.UTC)
+
+	charge := creditpurchase.Charge{
+		ChargeBase: creditpurchase.ChargeBase{
+			ManagedResource: meta.ManagedResource{
+				NamespacedModel: models.NamespacedModel{
+					Namespace: "ns",
+				},
+				ManagedModel: models.ManagedModel{
+					CreatedAt: now,
+					UpdatedAt: now,
+				},
+				ID: "grant-1",
+			},
+			Intent: creditpurchase.Intent{
+				Intent: meta.Intent{
+					Name:       "Promo credits",
+					CustomerID: "cust-1",
+					Currency:   currencyx.Code("USD"),
+				},
+				CreditAmount: alpacadecimal.RequireFromString("25"),
+				Settlement:   creditpurchase.NewSettlement(creditpurchase.PromotionalSettlement{}),
+			},
+			Status: creditpurchase.StatusActive,
+		},
+	}
+
+	grant, err := toAPIBillingCreditGrant(charge)
+	require.NoError(t, err)
+	require.Equal(t, api.BillingCreditFundingMethodNone, grant.FundingMethod)
+	require.Nil(t, grant.Purchase)
+	require.Equal(t, "25", grant.Amount)
+}

openmeter/billing/creditgrant/service/service.go

@@ -84,15 +84,37 @@ func (s *service) Create(ctx context.Context, input creditgrant.CreateInput) (cr
 	// Build the credit purchase intent
 	intent := toIntent(input)
 
-	result, err := s.creditPurchaseService.Create(ctx, creditpurchase.CreateInput{
+	result, err := s.chargesService.Create(ctx, charges.CreateInput{
 		Namespace: input.Namespace,
-		Intent:    intent,
+		Intents:   charges.ChargeIntents{charges.NewChargeIntent(intent)},
 	})
 	if err != nil {
-		return creditpurchase.Charge{}, fmt.Errorf("create credit purchase charge: %w", err)
+		return creditpurchase.Charge{}, fmt.Errorf("create credit grant charge: %w", err)
 	}
 
-	return result.Charge, nil
+	if len(result) != 1 {
+		return creditpurchase.Charge{}, fmt.Errorf("expected 1 created charge, got %d", len(result))
+	}
+
+	createdChargeID, err := result[0].GetChargeID()
+	if err != nil {
+		return creditpurchase.Charge{}, fmt.Errorf("get created charge id: %w", err)
+	}
+
+	charge, err := s.chargesService.GetByID(ctx, charges.GetByIDInput{
+		ChargeID: createdChargeID,
+		Expands:  meta.Expands{meta.ExpandRealizations},
+	})
+	if err != nil {
+		return creditpurchase.Charge{}, fmt.Errorf("get created credit grant charge: %w", err)
+	}
+
+	cpCharge, err := charge.AsCreditPurchaseCharge()
+	if err != nil {
+		return creditpurchase.Charge{}, fmt.Errorf("charge is not a credit purchase: %w", err)
+	}
+
+	return cpCharge, nil
 }
 
 func (s *service) Get(ctx context.Context, input creditgrant.GetInput) (creditpurchase.Charge, error) {