---
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`

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.
    - `amount` string, required — 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` BillingCreditGrantTaxConfig — Tax configuration for a credit grant. Tax configuration should be provided to ensure correct revenue recognition, including for externally funded grants.
    - `behavior` 'inclusive' | 'exclusive' — Tax behavior. This enum is used to specify whether tax is included in the price or excluded from the price.
    - `tax_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.
  - `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.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found

---

[API](https://skmtc.net/openmeterio/apis/openmeter-api.md) · [All operations](https://skmtc.net/openmeterio/apis/openmeter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openmeterio/openmeter-api/revisions/327f2080730f/schema)