feat(api): add invoice V3 GET endpoint (#4541)

Author: borosr

.agents/skills/api/rules/aip-126-enums.md

@@ -3,5 +3,5 @@
 Reference: https://kong-aip.netlify.app/aip/126/
 
 - All enum wire values must be `snake_case` (enforced as an error by the `casing-aip-errors` linter rule).
-- Every enum must define an `unknown` member as the zero/default value.
+- Prefer defining an `unknown` member as the zero/default value. This is a recommendation, not a requirement — most domains (charges, subscriptions, currencies) omit it, so do not flag its absence as a violation.
 - Prefer enums over booleans for two-state fields — this allows a third state to be added later without a breaking change.

api/spec/packages/aip-client-javascript/README.md

@@ -24,6 +24,7 @@ TypeSpec definitions and ships fully-typed request and response models.
   - [Subscriptions](#subscriptions)
   - [Apps](#apps)
   - [Billing](#billing)
+  - [Invoices](#invoices)
   - [Tax](#tax)
   - [Currencies](#currencies)
   - [Features](#features)
@@ -190,6 +191,12 @@ The full call path, HTTP route, and a short description are listed below.
 | `client.billing.updateProfile` | `PUT /openmeter/profiles/{id}`    | Update a billing profile.                                                                                                                                                                                                                                                                                                |
 | `client.billing.deleteProfile` | `DELETE /openmeter/profiles/{id}` | Delete a billing profile. Only such billing profiles can be deleted that are: - not the default profile - not pinned to any customer using customer overrides - only have finalized invoices                                                                                                                             |
 
+### Invoices
+
+| Method                | HTTP                                          | Description                                                                                                                                       |
+| --------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `client.invoices.get` | `GET /openmeter/billing/invoices/{invoiceId}` | Get a billing invoice by ID. Returns the full invoice resource including line items, status details, totals, and workflow configuration snapshot. |
+
 ### Tax
 
 | Method                  | HTTP                                      | Description |

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

@@ -5,6 +5,7 @@ export * from './entitlements.js'
 export * from './subscriptions.js'
 export * from './apps.js'
 export * from './billing.js'
+export * from './invoices.js'
 export * from './tax.js'
 export * from './currencies.js'
 export * from './features.js'

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

@@ -0,0 +1,21 @@
+import { type Client, http } from '../core.js'
+import { type Result, type RequestOptions } from '../lib/types.js'
+import { request } from '../lib/request.js'
+import { encodePath, toURLSearchParams, encodeSort } from '../lib/encodings.js'
+import type {
+  GetInvoiceRequest,
+  GetInvoiceResponse,
+} from '../models/operations/invoices.js'
+
+export function getInvoice(
+  client: Client,
+  req: GetInvoiceRequest,
+  options?: RequestOptions,
+): Promise<Result<GetInvoiceResponse>> {
+  const path = encodePath('openmeter/billing/invoices/{invoiceId}', {
+    invoiceId: req.invoiceId,
+  })
+  return request(() =>
+    http(client).get(path, options).json<GetInvoiceResponse>(),
+  )
+}

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

@@ -6,6 +6,7 @@ export { Entitlements } from './sdk/entitlements.js'
 export { Subscriptions } from './sdk/subscriptions.js'
 export { Apps } from './sdk/apps.js'
 export { Billing } from './sdk/billing.js'
+export { Invoices } from './sdk/invoices.js'
 export { Tax } from './sdk/tax.js'
 export { Currencies } from './sdk/currencies.js'
 export { Features } from './sdk/features.js'
@@ -38,6 +39,7 @@ export type * from './models/operations/entitlements.js'
 export type * from './models/operations/subscriptions.js'
 export type * from './models/operations/apps.js'
 export type * from './models/operations/billing.js'
+export type * from './models/operations/invoices.js'
 export type * from './models/operations/tax.js'
 export type * from './models/operations/currencies.js'
 export type * from './models/operations/features.js'
@@ -62,11 +64,15 @@ export type {
   CreateLabels,
   TaxConfigStripe,
   TaxConfigExternalInvoicing,
-  FlatFeeDiscounts,
+  ChargeFlatFeeDiscounts,
   PriceFree,
   WorkflowCollectionAlignmentSubscription,
   WorkflowPaymentChargeAutomaticallySettings,
   WorkflowPaymentSendInvoiceSettings,
+  InvoiceExternalReferences,
+  InvoiceAvailableActionDetails,
+  InvoiceWorkflowInvoicingSettings,
+  InvoiceLineExternalReferences,
   LlmCostProvider,
   LlmCostModel,
   RateCardStaticEntitlement,
@@ -91,6 +97,7 @@ export type {
   PriceUnit,
   RateCardDiscounts,
   Totals,
+  InvoiceLineCreditsApplied,
   FeatureManualUnitCost,
   FeatureLlmUnitCostPricing,
   LlmCostModelPricing,
@@ -109,6 +116,7 @@ export type {
   SubscriptionReference,
   AddonReference,
   AppReference,
+  ChargeReference,
   CurrencyFiat,
   FeatureReference,
   Event,
@@ -149,7 +157,6 @@ export type {
   QueryFilterStringMapItem,
   CustomerKeyReference,
   CustomerUsageAttribution,
-  BillingAddress,
   Address,
   AppStripeCreateCheckoutSessionCustomerUpdate,
   AppStripeCreateCheckoutSessionConsentCollectionPaymentMethodReuseAgreement,
@@ -173,6 +180,11 @@ export type {
   TaxCodeAppMapping,
   PartyTaxIdentity,
   WorkflowInvoicingSettings,
+  InvoiceValidationIssue,
+  InvoiceAvailableActions,
+  InvoiceLineAmountDiscount,
+  InvoiceLineUsageDiscount,
+  InvoiceLineBaseDiscount,
   ListCurrenciesParamsFilter,
   CurrencyCustom,
   CreateCurrencyCustomRequest,
@@ -206,6 +218,7 @@ export type {
   PlanAddon,
   CreatePlanAddonRequest,
   ProfileAppReferences,
+  InvoiceWorkflowAppsReferences,
   ListEventsParamsFilter,
   ResourceFilters,
   FieldFilters,
@@ -220,6 +233,7 @@ export type {
   Customer,
   UpsertCustomerRequest,
   PartyAddresses,
+  InvoiceCustomer,
   AppStripeCreateCheckoutSessionConsentCollection,
   ListCustomerEntitlementAccessResponseData,
   WorkflowCollectionAlignmentAnchored,
@@ -233,6 +247,9 @@ export type {
   CreateTaxCodeRequest,
   TaxCode,
   UpsertTaxCodeRequest,
+  InvoiceWorkflow,
+  InvoiceStatusDetails,
+  InvoiceLineDiscounts,
   InvoiceUsageQuantityDetail,
   GovernanceFeatureAccess,
   CustomerData,
@@ -244,7 +261,7 @@ export type {
   PricePagePaginatedResponse,
   CreateCreditGrantRequest,
   CreditGrant,
-  CreateFlatFeeChargeRequest,
+  CreateChargeFlatFeeRequest,
   WorkflowTaxSettings,
   SubscriptionAddonPagePaginatedResponse,
   PlanAddonPagePaginatedResponse,
@@ -253,26 +270,32 @@ export type {
   MeterQueryRequest,
   CustomerPagePaginatedResponse,
   Party,
+  Supplier,
   AppStripeCreateCheckoutSessionRequestOptions,
   TaxCodePagePaginatedResponse,
+  InvoiceWorkflowSettings,
+  InvoiceDetailedLine,
   CurrencyPagePaginatedResponse,
   GovernanceQueryResult,
   Feature,
   CreateFeatureRequest,
   UpdateFeatureRequest,
   CreditGrantPagePaginatedResponse,
   BadRequest,
+  InvoiceBase,
   CustomerStripeCreateCheckoutSessionRequest,
   WorkflowCollectionSettings,
   AppPagePaginatedResponse,
   ProfileApps,
   GovernanceQueryResponse,
-  FlatFeeCharge,
-  UsageBasedCharge,
-  CreateUsageBasedChargeRequest,
+  ChargeFlatFee,
+  ChargeUsageBased,
+  CreateChargeUsageBasedRequest,
+  InvoiceLineRateCard,
   RateCard,
   FeaturePagePaginatedResponse,
   Workflow,
+  InvoiceStandardLine,
   PlanPhase,
   Addon,
   CreateAddonRequest,
@@ -286,10 +309,12 @@ export type {
   UpsertPlanRequest,
   AddonPagePaginatedResponse,
   ProfilePagePaginatedResponse,
+  InvoiceStandard,
   PlanPagePaginatedResponse,
   SortQueryInput,
   BaseErrorInput,
   WorkflowPaymentSendInvoiceSettingsInput,
+  InvoiceWorkflowInvoicingSettingsInput,
   EventInput,
   UnauthorizedInput,
   ForbiddenInput,
@@ -313,19 +338,23 @@ export type {
   GovernanceQueryRequestInput,
   IngestedEventInput,
   SubscriptionCancelInput,
+  InvoiceWorkflowInput,
   InvoiceUsageQuantityDetailInput,
   CreateCreditGrantRequestInput,
   CreditGrantInput,
   WorkflowTaxSettingsInput,
   IngestedEventPaginatedResponseInput,
   MeterQueryRequestInput,
   AppStripeCreateCheckoutSessionRequestOptionsInput,
+  InvoiceWorkflowSettingsInput,
+  InvoiceDetailedLineInput,
   CreditGrantPagePaginatedResponseInput,
   BadRequestInput,
   CustomerStripeCreateCheckoutSessionRequestInput,
   WorkflowCollectionSettingsInput,
   RateCardInput,
   WorkflowInput,
+  InvoiceStandardLineInput,
   PlanPhaseInput,
   AddonInput,
   CreateAddonRequestInput,
@@ -338,5 +367,6 @@ export type {
   UpsertPlanRequestInput,
   AddonPagePaginatedResponseInput,
   ProfilePagePaginatedResponseInput,
+  InvoiceStandardInput,
   PlanPagePaginatedResponseInput,
 } from './models/types.js'

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

@@ -5,11 +5,11 @@ import type {
   AppStripeCreateCheckoutSessionResult,
   AppStripeCreateCustomerPortalSessionResult,
   ChargePagePaginatedResponse,
+  CreateChargeFlatFeeRequest,
+  CreateChargeUsageBasedRequest,
   CreateCreditAdjustmentRequest as CreateCreditAdjustmentRequestBody,
   CreateCreditGrantRequestInput,
   CreateCustomerRequest as CreateCustomerRequestBody,
-  CreateFlatFeeChargeRequest,
-  CreateUsageBasedChargeRequest,
   CreditAdjustment,
   CreditBalances,
   CreditGrant,
@@ -172,7 +172,7 @@ export type ListCustomerChargesResponse = ChargePagePaginatedResponse
 
 export type CreateCustomerChargesRequest = {
   customerId: string
-  body: CreateFlatFeeChargeRequest | CreateUsageBasedChargeRequest
+  body: CreateChargeFlatFeeRequest | CreateChargeUsageBasedRequest
 }
 export type CreateCustomerChargesResponse = z.output<
   typeof schemas.createCustomerChargesResponse

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

@@ -0,0 +1,7 @@
+import { z } from 'zod'
+import * as schemas from '../schemas.js'
+
+export type GetInvoiceRequest = {
+  invoiceId: string
+}
+export type GetInvoiceResponse = z.output<typeof schemas.getInvoiceResponse>