feat(api): add credit purchase idempotency key

api/spec/packages/aip-client-javascript/src/models/schemas.ts

@@ -3969,6 +3969,7 @@ export const createCreditGrantRequest = z
         'Draw-down priority of the grant. Lower values have higher priority.',
       ),
     expires_after: iso8601Duration.optional(),
+    key: externalResourceKey.optional(),
   })
   .describe('CreditGrant create request.')
 
@@ -4011,6 +4012,7 @@ export const creditGrant = z
         'Draw-down priority of the grant. Lower values have higher priority.',
       ),
     expires_after: iso8601Duration.optional(),
+    key: externalResourceKey.optional(),
     expires_at: dateTime.optional(),
     voided_at: dateTime.optional(),
     status: creditGrantStatus,

api/spec/packages/aip-client-javascript/src/models/types.ts

@@ -3569,6 +3569,13 @@ export interface CreateCreditGrantRequest {
    * Defaults to never expiring.
    */
   expires_after?: string
+  /**
+   * Idempotency key for the credit grant creation request.
+   *
+   * When provided, reusing the same key returns an HTTP 409 Conflict instead of
+   * creating a duplicate grant, which makes create requests safe to retry.
+   */
+  key?: string
 }
 
 /**
@@ -3626,6 +3633,13 @@ export interface CreditGrant {
    * Defaults to never expiring.
    */
   expires_after?: string
+  /**
+   * Idempotency key for the credit grant creation request.
+   *
+   * When provided, reusing the same key returns an HTTP 409 Conflict instead of
+   * creating a duplicate grant, which makes create requests safe to retry.
+   */
+  key?: string
   /**
    * The timestamp when the credit grant expires.
    *
@@ -5432,6 +5446,13 @@ export interface CreateCreditGrantRequestInput {
    * Defaults to never expiring.
    */
   expires_after?: string
+  /**
+   * Idempotency key for the credit grant creation request.
+   *
+   * When provided, reusing the same key returns an HTTP 409 Conflict instead of
+   * creating a duplicate grant, which makes create requests safe to retry.
+   */
+  key?: string
 }
 
 export interface CreditGrantInput {
@@ -5483,6 +5504,13 @@ export interface CreditGrantInput {
    * Defaults to never expiring.
    */
   expires_after?: string
+  /**
+   * Idempotency key for the credit grant creation request.
+   *
+   * When provided, reusing the same key returns an HTTP 409 Conflict instead of
+   * creating a duplicate grant, which makes create requests safe to retry.
+   */
+  key?: string
   /**
    * The timestamp when the credit grant expires.
    *

api/spec/packages/aip/src/customers/credits/grant.tsp

@@ -193,6 +193,15 @@ model CreditGrant {
   @visibility(Lifecycle.Create)
   expires_after?: Shared.ISO8601Duration;
 
+  /**
+   * Idempotency key for the credit grant creation request.
+   *
+   * When provided, reusing the same key returns an HTTP 409 Conflict instead of
+   * creating a duplicate grant, which makes create requests safe to retry.
+   */
+  @visibility(Lifecycle.Create)
+  key?: Shared.ExternalResourceKey;
+
   /**
    * The timestamp when the credit grant expires.
    *

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

@@ -340,6 +340,7 @@ func fromAPICreateCreditGrantRequest(ns string, customerID api.ULID, body api.Cr
 		FundingMethod: fromAPIBillingCreditFundingMethod(body.FundingMethod),
 		Priority:      body.Priority,
 		Labels:        lo.FromPtrOr(body.Labels, api.Labels{}),
+		Key:           body.Key,
 	}
 
 	if body.ExpiresAfter != nil {

api/v3/openapi.yaml

@@ -8636,6 +8636,14 @@ components:
             The duration after which the credit grant expires.
 
             Defaults to never expiring.
+        key:
+          allOf:
+            - $ref: '#/components/schemas/ExternalResourceKey'
+          description: |-
+            Idempotency key for the credit grant creation request.
+
+            When provided, reusing the same key returns an HTTP 409 Conflict instead of
+            creating a duplicate grant, which makes create requests safe to retry.
       additionalProperties: false
       description: CreditGrant create request.
     CreateCreditGrantTaxConfig:

e2e/customer_credits_v3_test.go

@@ -84,3 +84,68 @@ func TestV3CreateCreditGrantMissingTaxCode(t *testing.T) {
 	}
 	assert.True(t, mentionsTaxCode, "response should name the missing tax code, problem: %+v", problem)
 }
+
+func TestV3CreateCreditGrantIdempotencyKey(t *testing.T) {
+	c := newV3Client(t)
+	currency := apiv3.CurrencyCode("USD")
+
+	createCustomer := func(prefix string) string {
+		status, customer, problem := c.CreateCustomer(apiv3.CreateCustomerRequest{
+			Key:      uniqueKey(prefix),
+			Name:     "Credit Grant Idempotency Test Customer",
+			Currency: &currency,
+		})
+		require.Equal(t, http.StatusCreated, status, "problem: %+v", problem)
+		require.NotNil(t, customer)
+		return customer.Id
+	}
+
+	grant := func(key *string) apiv3.CreateCreditGrantRequest {
+		return apiv3.CreateCreditGrantRequest{
+			Name:          "idempotency grant",
+			Amount:        apiv3.Numeric("10"),
+			Currency:      currency,
+			FundingMethod: apiv3.BillingCreditFundingMethodNone,
+			Key:           key,
+		}
+	}
+
+	t.Run("reusing a key for the same customer returns 409", func(t *testing.T) {
+		customerID := createCustomer("credit_grant_idem_conflict")
+		key := ulid.Make().String()
+
+		status, _, problem := c.CreateCreditGrant(customerID, grant(&key))
+		require.Equal(t, http.StatusCreated, status, "first create must succeed, problem: %+v", problem)
+
+		status, _, problem = c.CreateCreditGrant(customerID, grant(&key))
+		require.Equal(t, http.StatusConflict, status, "reusing an idempotency key must be a 409, problem: %+v", problem)
+	})
+
+	t.Run("omitting the key allows duplicates", func(t *testing.T) {
+		customerID := createCustomer("credit_grant_idem_nil")
+
+		status, _, problem := c.CreateCreditGrant(customerID, grant(nil))
+		require.Equal(t, http.StatusCreated, status, "problem: %+v", problem)
+
+		status, _, problem = c.CreateCreditGrant(customerID, grant(nil))
+		require.Equal(t, http.StatusCreated, status, "grants without a key must not collide, problem: %+v", problem)
+	})
+
+	t.Run("the same key conflicts across different customers in a namespace", func(t *testing.T) {
+		key := ulid.Make().String()
+
+		status, _, problem := c.CreateCreditGrant(createCustomer("credit_grant_idem_cust_a"), grant(&key))
+		require.Equal(t, http.StatusCreated, status, "problem: %+v", problem)
+
+		status, _, problem = c.CreateCreditGrant(createCustomer("credit_grant_idem_cust_b"), grant(&key))
+		require.Equal(t, http.StatusConflict, status, "the key is unique per namespace, not per customer, problem: %+v", problem)
+	})
+
+	t.Run("an over-length key is rejected with 400", func(t *testing.T) {
+		customerID := createCustomer("credit_grant_idem_overlong")
+		key := strings.Repeat("k", 257)
+
+		status, _, problem := c.CreateCreditGrant(customerID, grant(&key))
+		require.Equal(t, http.StatusBadRequest, status, "an over-length key must be a 400, problem: %+v", problem)
+	})
+}

openmeter/billing/charges/creditpurchase/adapter/charge.go

@@ -76,6 +76,7 @@ func (a *adapter) CreateCharge(ctx context.Context, in creditpurchase.CreateChar
 			SetNillablePriority(in.Intent.Priority).
 			SetFeatureFilters(pq.StringArray(in.Intent.FeatureFilters.Normalize())).
 			SetSettlement(in.Intent.Settlement).
+			SetNillableKey(in.Intent.Key).
 			SetStatusDetailed(initialStatus)
 
 		create, err = chargemeta.Create(create, chargemeta.CreateInput{

openmeter/billing/charges/creditpurchase/adapter/mapper.go

@@ -32,6 +32,7 @@ func MapChargeBaseFromDB(dbEntity *entdb.ChargeCreditPurchase) creditpurchase.Ch
 				FeatureFilters:      creditpurchase.FeatureFilters(dbEntity.FeatureFilters).Normalize(),
 				Settlement:          dbEntity.Settlement,
 			},
+			Key: dbEntity.Key,
 		},
 	}
 }

openmeter/billing/charges/creditpurchase/charge.go

@@ -117,6 +117,9 @@ func (c Charge) Validate() error {
 type Intent struct {
 	meta.Intent
 	IntentMutableFields
+
+	// Key is the optional idempotency key: a retried create with the same key returns a conflict.
+	Key *string `json:"key,omitempty"`
 }
 
 type IntentMutableFields struct {

openmeter/billing/creditgrant/service.go

@@ -65,6 +65,8 @@ type CreateInput struct {
 	TaxConfig     *productcatalog.TaxConfig
 	Filters       *GrantFilters
 	ExpiresAfter  *datetime.ISODuration
+	// Key is the optional idempotency key: a retried create with the same key returns a conflict.
+	Key *string
 }
 
 type GrantFilters struct {

openmeter/billing/creditgrant/service/service.go

@@ -237,6 +237,7 @@ func toIntent(input creditgrant.CreateInput) creditpurchase.Intent {
 			ExpiresAt:    calculateExpiresAt(effectiveAt, input.ExpiresAfter),
 			Settlement:   toSettlement(input),
 		},
+		Key: input.Key,
 	}
 
 	if input.Filters != nil {