--- title: "Update credit grant external settlement status" method: POST path: "/openmeter/customers/{customerId}/credits/grants/{creditGrantId}/settlement/external" tags: ["OpenMeter Customers"] --- # Update credit grant external settlement status `POST /openmeter/customers/{customerId}/credits/grants/{creditGrantId}/settlement/external` ## Request - Base URL: `http://localhost:8888/api/v3` - URL: `http://localhost:8888/api/v3/openmeter/customers/{customerId}/credits/grants/{creditGrantId}/settlement/external` - Auth: none declared Update the payment settlement status of an externally funded credit grant. Use this endpoint to synchronize the payment state of an external payment with the system so that revenue recognition and credit availability work as expected. ## Path parameters - `customerId` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `creditGrantId` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). ## Request body - UpdateCreditGrantExternalSettlementRequest: Request body for updating the external payment settlement status of a credit grant. - `status` 'pending' | 'authorized' | 'settled', required: Credit purchase payment settlement status. - `pending`: Payment has been initiated and is not yet authorized. - `authorized`: Payment has been authorized. - `settled`: Payment has been settled. ## Response `200` CreditGrant updated response. - BillingCreditGrant: A credit grant allocates credits to a customer. Credits are drawn down against charges according to the settlement mode configured on the rate card. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `name` string, required: Display name of the resource. Between 1 and 256 characters. - `description` string: Optional description of the resource. Maximum 1024 characters. - `labels` Labels: Labels store metadata of an entity that can be used for filtering an entity list or for searching across entity types. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_". - `created_at` string, date-time, required: [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `updated_at` string, date-time, required: [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `deleted_at` string, date-time: [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `funding_method` 'none' | 'invoice' | 'external', required: The funding method describes how the grant is funded. - `none`: No funding workflow applies, for example promotional grants - `invoice`: The grant is funded by an in-system invoice flow - `external`: The grant is funded outside the system (e.g., wire transfer, external invoice, or manual reconciliation) - `currency` union, required: Fiat or custom currency code. - string: Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - string: Custom currency code. It should be a unique code but not conflicting with any existing fiat currency codes. - `amount` string, required: Numeric represents an arbitrary precision number. - `purchase` BillingCreditGrantPurchase: Purchase and payment terms of the grant. - `currency` string, required: Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - `per_unit_cost_basis` string: Numeric represents an arbitrary precision number. - `resolved_cost_basis` BillingChargeResolvedCostBasis: Fiat conversion rate a custom-currency charge is invoiced at. Present once the cost basis is resolved; dynamic cost bases are exposed only after the service period has started. - `fiat_currency` string, required: Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience. - `rate` string, required: Numeric represents an arbitrary precision number. - `cost_basis_id` string: ULID (Universally Unique Lexicographically Sortable Identifier). - `resolved_at` string, date-time, required: [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `amount` string: Numeric represents an arbitrary precision number. - `availability_policy` 'on_creation': When credits become available for consumption. - `on_creation`: Credits are available as soon as the grant is created. - `on_authorization`: Credits are available once the payment is authorized. - `on_settlement`: Credits are available once the payment is settled. - `settlement_status` 'pending' | 'authorized' | 'settled': Credit purchase payment settlement status. - `pending`: Payment has been initiated and is not yet authorized. - `authorized`: Payment has been authorized. - `settled`: Payment has been settled. - `tax_config` TaxCodeConfig: Tax configuration for a billable resource. Applies a tax code and tax behavior to the resulting invoice line items. When not set, the applicable default is used: the billing profile default tax configuration, then the organization default tax code. - `behavior` 'inclusive' | 'exclusive': Tax behavior. This enum is used to specify whether tax is included in the price or excluded from the price. - `code` TaxCodeReference: TaxCode reference. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `invoice` BillingCreditGrantInvoiceReference: Invoice references for the grant. - `id` string: ULID (Universally Unique Lexicographically Sortable Identifier). - `line` object: Identifier of the invoice line associated with the grant. - `id` string, required: ULID (Universally Unique Lexicographically Sortable Identifier). - `filters` BillingCreditGrantFilters: Filters for the credit grant. - `features` ResourceKey[]: Limit the credit grant to specific features. If no features are specified, the credit grant can be used for any feature. - `plans` BillingCreditGrantPlanFilter[]: Limit credits to charges from these plans. Entries are alternatives; when features are also specified, both dimensions must match. Omission or an empty list leaves plans unrestricted. - `key` string, required: A key is a unique string that is used to identify a resource. - `version` VersionFilter: An integer version comparison. Exactly one operator must be provided. - `eq` integer: Match this exact version. - `oeq` integer[]: Match one of these versions. - `gte` integer: Match this version and later versions. - `lte` integer: Match this version and earlier versions. - `priority` integer: Draw-down priority of the grant. Lower values have higher priority. - `effective_at` string, date-time: [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `key` string: ExternalResourceKey is a unique string that is used to identify a resource in an external system. - `expires_at` string, date-time: [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `voided_at` string, date-time: [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC. - `status` 'pending' | 'active' | 'expired' | 'voided', required: Credit grant lifecycle status. - `pending`: The credit block has been created but is not yet valid. (`effective_at` is in the future or availability_policy is not met) - `active`: The credit block is currently valid and eligible for consumption. (`effective_at` is in the past, `expires_at` is in the future and availability_policy is met) - `expired`: The credit block expired with remaining unused balance, `expires_at` time has passed. - `voided`: The credit block was voided. Remaining balance is forfeited. - `validation_issues` BillingValidationIssue[]: Validation issues found while processing the credit grant. Present only when there are one or more validation findings. An empty list is omitted. - `code` string, required: Machine-readable error code. - `message` string, required: Human-readable description of the error. - `attributes` object: Additional structured context. - `severity` 'critical' | 'warning', required: Severity level of a billing validation issue. - `field` string: JSON path to the field that caused the validation issue, if applicable. - `component` string: Component that reported the validation issue, if applicable. ## Other responses - `400`: Bad Request - `401`: Unauthorized - `403`: Forbidden - `404`: Not Found ## Changes - **2026-09-30** (v3) `88e3c05f26d3`: 1 warning, 1 info - removed the optional property `filters/plans/items/version/allOf[#/components/schemas/VersionFilter]/in` from the response with the `200` status - added the optional property `filters/plans/items/version/allOf[#/components/schemas/VersionFilter]/oeq` to the response with the `200` status - **2026-09-24** (v3) `7480819ae98b`: 1 info - added the optional property `filters/plans` to the response with the `200` status - **2026-09-21** (v3) `159bfd1e78cf`: 2 info - added `#/components/schemas/TaxCodeConfig` to the `tax_config` response property `allOf` list for the response status `200` - removed `#/components/schemas/BillingCreditGrantTaxConfig` from the `tax_config` response property `allOf` list for the response status `200` - **2026-09-07** (v3) `9082b60c6dd4`: 1 info - added the optional property `validation_issues` to the response with the `200` status - …earlier changes not shown [Operation history](https://skmtc.dev/openmeterio/apis/openmeter-api/changes/openmeter/customers/:customerId/credits/grants/:creditGrantId/settlement/external/post.md) --- [API](https://skmtc.dev/openmeterio/apis/openmeter-api.md) - [All operations](https://skmtc.dev/openmeterio/apis/openmeter-api/llms.txt) - [OpenAPI document](https://skmtc.dev/openmeterio/apis/openmeter-api/revisions/c0b1e490432b?raw)