feat: grant voiding

api/spec/packages/aip-client-javascript/src/funcs/customers.ts

@@ -37,6 +37,8 @@ import type {
   GetCustomerCreditBalanceResponse,
   CreateCreditAdjustmentRequest,
   CreateCreditAdjustmentResponse,
+  VoidCreditGrantRequest,
+  VoidCreditGrantResponse,
   UpdateCreditGrantExternalSettlementRequest,
   UpdateCreditGrantExternalSettlementResponse,
   ListCreditTransactionsRequest,
@@ -580,6 +582,54 @@ export function createCreditAdjustment(
   })
 }
 
+/**
+ * Void credit grant
+ *
+ * Void a credit grant, forfeiting the remaining unused balance.
+ *
+ * Voiding is a forward-looking, irreversible operation. Credits already consumed
+ * by usage remain unaffected — only the remaining balance is forfeited. The grant
+ * reads as `voided` status afterwards. Payment state is not adjusted when
+ * `payment_adjustment` is `none`, so invoice-backed or externally collected
+ * payments may still collect the original amount. Only `active` grants can be
+ * voided; voiding a pending, expired, or fully consumed grant returns a conflict.
+ * Retrying a successful void is an idempotent success.
+ *
+ * POST /openmeter/customers/{customerId}/credits/grants/{creditGrantId}/void
+ */
+export function voidCreditGrant(
+  client: Client,
+  req: VoidCreditGrantRequest,
+  options?: RequestOptions,
+): Promise<Result<VoidCreditGrantResponse>> {
+  return request(() => {
+    const path = `openmeter/customers/${(() => {
+      if (req.customerId === undefined) {
+        throw new Error('missing path parameter: customerId')
+      }
+      return encodeURIComponent(String(req.customerId))
+    })()}/credits/grants/${(() => {
+      if (req.creditGrantId === undefined) {
+        throw new Error('missing path parameter: creditGrantId')
+      }
+      return encodeURIComponent(String(req.creditGrantId))
+    })()}/void`
+    const body = toWire(req.body, schemas.voidCreditGrantBody)
+    if (client._options.validate) {
+      assertValid(schemas.voidCreditGrantBodyWire, body)
+    }
+    return http(client)
+      .post(path, { ...options, json: body })
+      .json()
+      .then((data) => {
+        if (client._options.validate) {
+          assertValid(schemas.voidCreditGrantResponseWire, data)
+        }
+        return fromWire(data, schemas.voidCreditGrantResponse)
+      })
+  })
+}
+
 /**
  * Update credit grant external settlement status
  *

api/spec/packages/aip-client-javascript/src/index.ts

@@ -374,6 +374,7 @@ export type {
   CreateCreditGrantPurchaseInput,
   RateCardMeteredEntitlementInput,
   CreditGrantPurchaseInput,
+  VoidCreditGrantRequestInput,
   UnitConfigInput,
   WorkflowInvoicingSettingsInput,
   GovernanceQueryRequestInput,

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

@@ -34,6 +34,7 @@ import type {
   UpsertAppCustomerDataRequest,
   UpsertCustomerBillingDataRequest,
   UpsertCustomerRequest as UpsertCustomerRequestBody,
+  VoidCreditGrantRequestInput,
 } from '../types.js'
 
 export type CreateCustomerRequest = AcceptDateStrings<CreateCustomerRequestBody>
@@ -156,6 +157,13 @@ export type CreateCreditAdjustmentRequest = AcceptDateStrings<{
 }>
 export type CreateCreditAdjustmentResponse = CreditAdjustment
 
+export type VoidCreditGrantRequest = AcceptDateStrings<{
+  customerId: string
+  creditGrantId: string
+  body: VoidCreditGrantRequestInput
+}>
+export type VoidCreditGrantResponse = CreditGrant
+
 export type UpdateCreditGrantExternalSettlementRequest = AcceptDateStrings<{
   customerId: string
   creditGrantId: string

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

@@ -571,11 +571,18 @@ export const stringFieldFilterExact = z
     'Filters on the given string field value by exact match. All properties are optional; provide exactly one to specify the comparison.',
   )
 
+export const creditGrantVoidPaymentAdjustment = z
+  .enum(['none'])
+
+  .describe(
+    'Describes how voiding a credit grant adjusts related payment state. - `none`: Voiding does not adjust invoices, payment authorization, settlement, payment intents, or external collection state.',
+  )
+
 export const creditTransactionType = z
-  .enum(['funded', 'consumed', 'expired'])
+  .enum(['funded', 'consumed', 'expired', 'voided'])
 
   .describe(
-    'The type of the credit transaction. - `funded`: Credit granted and available for consumption. - `consumed`: Credit consumed by usage or fees. - `expired`: Credit removed because it expired before being used.',
+    'The type of the credit transaction. - `funded`: Credit granted and available for consumption. - `consumed`: Credit consumed by usage or fees. - `expired`: Credit removed because it expired before being used. - `voided`: Credit removed because the grant was voided before being used.',
   )
 
 export const chargesExpand = z
@@ -2678,6 +2685,14 @@ export const listPlansParamsFilter = z
   })
   .describe('Filter options for listing plans.')
 
+export const voidCreditGrantRequest = z
+  .object({
+    paymentAdjustment: creditGrantVoidPaymentAdjustment
+      .optional()
+      .default('none'),
+  })
+  .describe('Request body for voiding a credit grant.')
+
 export const subscriptionCreate = z
   .object({
     labels: labels.optional(),
@@ -5864,6 +5879,15 @@ export const createCreditAdjustmentBody = createCreditAdjustmentRequest
 
 export const createCreditAdjustmentResponse = creditAdjustment
 
+export const voidCreditGrantPathParams = z.object({
+  customerId: ulid,
+  creditGrantId: ulid,
+})
+
+export const voidCreditGrantBody = voidCreditGrantRequest
+
+export const voidCreditGrantResponse = creditGrant
+
 export const updateCreditGrantExternalSettlementPathParams = z.object({
   customerId: ulid,
   creditGrantId: ulid,
@@ -7036,11 +7060,18 @@ export const stringFieldFilterExactWire = z
     'Filters on the given string field value by exact match. All properties are optional; provide exactly one to specify the comparison.',
   )
 
+export const creditGrantVoidPaymentAdjustmentWire = z
+  .enum(['none'])
+
+  .describe(
+    'Describes how voiding a credit grant adjusts related payment state. - `none`: Voiding does not adjust invoices, payment authorization, settlement, payment intents, or external collection state.',
+  )
+
 export const creditTransactionTypeWire = z
-  .enum(['funded', 'consumed', 'expired'])
+  .enum(['funded', 'consumed', 'expired', 'voided'])
 
   .describe(
-    'The type of the credit transaction. - `funded`: Credit granted and available for consumption. - `consumed`: Credit consumed by usage or fees. - `expired`: Credit removed because it expired before being used.',
+    'The type of the credit transaction. - `funded`: Credit granted and available for consumption. - `consumed`: Credit consumed by usage or fees. - `expired`: Credit removed because it expired before being used. - `voided`: Credit removed because the grant was voided before being used.',
   )
 
 export const chargesExpandWire = z
@@ -9145,6 +9176,14 @@ export const listPlansParamsFilterWire = z
   })
   .describe('Filter options for listing plans.')
 
+export const voidCreditGrantRequestWire = z
+  .strictObject({
+    payment_adjustment: creditGrantVoidPaymentAdjustmentWire
+      .optional()
+      .default('none'),
+  })
+  .describe('Request body for voiding a credit grant.')
+
 export const subscriptionCreateWire = z
   .strictObject({
     labels: labelsWire.optional(),
@@ -12354,6 +12393,15 @@ export const createCreditAdjustmentBodyWire = createCreditAdjustmentRequestWire
 
 export const createCreditAdjustmentResponseWire = creditAdjustmentWire
 
+export const voidCreditGrantPathParamsWire = z.object({
+  customerId: ulidWire,
+  creditGrantId: ulidWire,
+})
+
+export const voidCreditGrantBodyWire = voidCreditGrantRequestWire
+
+export const voidCreditGrantResponseWire = creditGrantWire
+
 export const updateCreditGrantExternalSettlementPathParamsWire = z.object({
   customerId: ulidWire,
   creditGrantId: ulidWire,

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

@@ -1768,6 +1768,18 @@ export interface ListPlansParamsFilter {
   currency?: StringFieldFilterExact
 }
 
+/** Request body for voiding a credit grant. */
+export interface VoidCreditGrantRequest {
+  /**
+   * How voiding adjusts payment state related to the grant.
+   *
+   * Currently only `none` is supported: voiding does not adjust invoices, payment
+   * authorization, settlement, payment intents, or external collection state. If
+   * payment later completes, the original invoiced amount may still be collected.
+   */
+  paymentAdjustment: 'none'
+}
+
 /** Subscription create request. */
 export interface SubscriptionCreate {
   labels?: Labels
@@ -2198,7 +2210,7 @@ export interface CreateCreditAdjustmentRequest {
 /** Filter options for listing credit transactions. */
 export interface ListCreditTransactionsParamsFilter {
   /** Filter credit transactions by type. */
-  type?: 'funded' | 'consumed' | 'expired'
+  type?: 'funded' | 'consumed' | 'expired' | 'voided'
   /** Filter credit transactions by currency. */
   currency?: BillingCurrencyCode
   /**
@@ -2235,7 +2247,7 @@ export interface CreditTransaction {
   /** The date and time the transaction was booked. */
   bookedAt: Date
   /** The type of credit transaction. */
-  type: 'funded' | 'consumed' | 'expired'
+  type: 'funded' | 'consumed' | 'expired' | 'voided'
   /** Currency of the balance affected by the transaction. */
   currency: BillingCurrencyCode
   /**
@@ -5592,6 +5604,18 @@ export interface CreditGrantPurchaseInput {
   settlementStatus?: 'pending' | 'authorized' | 'settled'
 }
 
+/** Request body for voiding a credit grant. */
+export interface VoidCreditGrantRequestInput {
+  /**
+   * How voiding adjusts payment state related to the grant.
+   *
+   * Currently only `none` is supported: voiding does not adjust invoices, payment
+   * authorization, settlement, payment intents, or external collection state. If
+   * payment later completes, the original invoiced amount may still be collected.
+   */
+  paymentAdjustment?: 'none'
+}
+
 /**
  * Unit conversion configuration.
  *

api/spec/packages/aip-client-javascript/src/sdk/customers.ts

@@ -19,6 +19,7 @@ import {
   listCreditGrants,
   getCustomerCreditBalance,
   createCreditAdjustment,
+  voidCreditGrant,
   updateCreditGrantExternalSettlement,
   listCreditTransactions,
   listCustomerCharges,
@@ -55,6 +56,8 @@ import type {
   GetCustomerCreditBalanceResponse,
   CreateCreditAdjustmentRequest,
   CreateCreditAdjustmentResponse,
+  VoidCreditGrantRequest,
+  VoidCreditGrantResponse,
   UpdateCreditGrantExternalSettlementRequest,
   UpdateCreditGrantExternalSettlementResponse,
   ListCreditTransactionsRequest,
@@ -349,6 +352,28 @@ export class CustomersCreditsGrants {
     )
   }
 
+  /**
+   * Void credit grant
+   *
+   * Void a credit grant, forfeiting the remaining unused balance.
+   *
+   * Voiding is a forward-looking, irreversible operation. Credits already consumed
+   * by usage remain unaffected — only the remaining balance is forfeited. The grant
+   * reads as `voided` status afterwards. Payment state is not adjusted when
+   * `payment_adjustment` is `none`, so invoice-backed or externally collected
+   * payments may still collect the original amount. Only `active` grants can be
+   * voided; voiding a pending, expired, or fully consumed grant returns a conflict.
+   * Retrying a successful void is an idempotent success.
+   *
+   * POST /openmeter/customers/{customerId}/credits/grants/{creditGrantId}/void
+   */
+  async void(
+    request: VoidCreditGrantRequest,
+    options?: RequestOptions,
+  ): Promise<VoidCreditGrantResponse> {
+    return unwrap(await voidCreditGrant(this._client, request, options))
+  }
+
   /**
    * Update credit grant external settlement status
    *

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

@@ -92,6 +92,19 @@ enum CreditGrantStatus {
   Voided: "voided",
 }
 
+/**
+ * Describes how voiding a credit grant adjusts related payment state.
+ *
+ * - `none`: Voiding does not adjust invoices, payment authorization, settlement,
+ *   payment intents, or external collection state.
+ */
+@friendlyName("BillingCreditGrantVoidPaymentAdjustment")
+@summary("Credit grant void payment adjustment")
+enum CreditGrantVoidPaymentAdjustment {
+  // No payment state is adjusted by the void operation.
+  None: "none",
+}
+
 /**
  * Tax configuration for a credit grant.
  *

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

@@ -9,6 +9,7 @@ namespace Customers;
  * - `funded`: Credit granted and available for consumption.
  * - `consumed`: Credit consumed by usage or fees.
  * - `expired`: Credit removed because it expired before being used.
+ * - `voided`: Credit removed because the grant was voided before being used.
  */
 @friendlyName("BillingCreditTransactionType")
 enum CreditTransactionType {
@@ -20,6 +21,9 @@ enum CreditTransactionType {
 
   // Credit removed because it expired before being used.
   Expired: "expired",
+
+  // Credit removed because the grant was voided before being used.
+  Voided: "voided",
 }
 
 // /**