Sign in
Grants

Create a grant.

post/v2/grants

Headers

Idempotency-Keystring

Non-empty idempotency key for deduplicating write requests on the same route.

Example:6f31c20e-725c-4be8-96f4-835042f67602

Optional. Duplicate keys within the same company namespace and route return 409.

Request body

OR

Example request

{
  "description": "Usage tracked for Acme.",
  "account_id": "account_0194f4e3a2b77c6aa91c4f6b4db2a980",
  "metric_id": "metric_0194f4e3a2b77c6aa91c4f6b4db2a980",
  "currency": "usd",
  "amount": "100.0",
  "expires_at": 1767225600,
  "effective_at": 1767225600
}

Response

Created.

idstring required

LedgerUp grant identifier.

descriptionstring nullable required

Optional description. Maximum 2048 Unicode scalar values.

account_idstring required

LedgerUp account identifier.

metric_idstring nullable required

LedgerUp metric identifier. Null for currency grants.

currencystring nullable required

Three-letter lowercase currency code. Amount is expressed in major currency units, not minor units. Null for metric grants.

amountstring required

Decimal amount serialized as a string.

expires_atinteger required

Unix timestamp in seconds.

accepted_atinteger required

Unix timestamp in seconds.

created_atinteger required

Unix timestamp in seconds.

updated_atinteger required

Unix timestamp in seconds.

status'active' | 'scheduled' | 'voided' | 'archived' | 'expired' required

Derived grant status. Voided and archived take precedence over expiration and scheduled activation.

archived_atinteger required

Unix timestamp in seconds.

contract_v1_idstring uuid nullable required

Optional public.contracts identifier.

effective_atinteger required

Unix timestamp in seconds.

Example response

{
  "id": "grant_0194f4e3a2b77c6aa91c4f6b4db2a980",
  "description": "Usage tracked for Acme.",
  "account_id": "account_0194f4e3a2b77c6aa91c4f6b4db2a980",
  "metric_id": "metric_0194f4e3a2b77c6aa91c4f6b4db2a980",
  "currency": "usd",
  "amount": "100.0",
  "expires_at": 1767225600,
  "accepted_at": 1767225600,
  "created_at": 1767225600,
  "updated_at": 1767225600,
  "status": "active",
  "archived_at": 1767225600,
  "effective_at": 1767225600
}

Changes