Leases tools · Ownrecord docs

leases_create: Lease wallet funds
leases_get: Get a lease
leases_settle: Settle a lease

`leases_create`

Lease wallet funds. Operation leases.create · Brand level · permission wallets:write · risk tier write · since M6

Reserves a block of a wallet's funds (amount, e.g. 5.00) for ttlSeconds (at most 900), so your service can meter high-frequency usage locally against it and settle in batches instead of calling Ownrecord for every charge. Never consume more than the lease's remaining.

The funds are taken from the wallet's credits in spend order (promo credits first, then subscription credits, then purchased credits, each soonest expiry first) and held until you settle the lease (leases.settle). If the lease reaches its TTL without a closing settle, its expiryPolicy applies:

release (default): the rest goes back to the wallet; a later settle gets lease_expired;
capture: all of the rest is charged as consumed;
hold_for_late_settle: the funds stay reserved for lateSettleWindowSeconds (default one day), and one settle in that window charges what was consumed and releases the rest. If none comes, lateSettleFallback applies (release by default, or capture). For services that keep a durable local consumption log and can recover after a crash.

The response includes suggestedNextAmount, sizing guidance from recent consumption. Retrying with the same Idempotency-Key returns the same lease.

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments

Argument	Type	Required	Description
`id`	ID (`wal_…`)	yes	The wallet to lease from (`wal_…`).
`amount`	object	yes	How much to lease, in the wallet's currency.
`ttlSeconds`	integer	yes	How long the lease lives, 1 to 900 seconds. (1–900)
`expiryPolicy`	one of `release`, `capture`, `hold_for_late_settle`	no	What happens if the lease reaches its TTL without a closing settle: `release` (default) returns the rest to the wallet, `capture` charges all of it, `hold_for_late_settle` keeps it reserved for a late settle.
`lateSettleWindowSeconds`	integer	no	`hold_for_late_settle` only: how long after the TTL a settle is still accepted (default 86400, at most 7 days). (1–604800)
`lateSettleFallback`	one of `release`, `capture`	no	`hold_for_late_settle` only: what happens when the window ends without a settle, `release` (default) or `capture`.
`metadata`	object	no	Your own key-value pairs (at most 50 keys). On updates the whole set is replaced.
`entity_id`	ID (`ent_…`)	no	Optional: the brand's legal entity (ent_…); `brand_id` alone is enough.
`brand_id`	ID (`brd_…`)	no	The brand to act on (brd_…), inside your API key's reach. Needed with an organization or entity key; a brand key acts on its own brand.
`idempotency_key`	string	no	A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters)
`dry_run`	boolean	no	true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)

Brand: pass brand_id with an organization or entity key; a brand key acts on its own brand.
Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.
Plan feature: needs usage_billing.enabled.

Errors

entitlement_required: The organization's plan doesn't include usage billing (usage_billing.enabled).
validation_failed: A field is malformed: an amount that isn't positive micros, a TTL outside 1–900 seconds, late-settle terms without hold_for_late_settle.
resource_not_found: No wallet with this ID in the brand and mode.
insufficient_funds: The wallet's spendable credits are less than amount (402).
wallet_fresh_balance_capped: The brand caps how much of recently bought credits can be used (402; §20 usage caps for fresh balances).
wallet_currency_mismatch: amount isn't in the wallet's currency.
wallet_frozen: The wallet is frozen.
wallet_closed: The wallet is closed.
idempotency_key_reused: The Idempotency-Key was already used for another lease or reservation of this wallet.
permission_denied: The credentials can't use this brand's wallets (wallets:write).

Examples

Lease 5.00 for five minutes

Arguments:

JSON

{
  "id": "wal_01m4ty3c2b5qx7mhd9k8w6s0b1",
  "amount": {
    "amount": "5000000",
    "currency": "EUR"
  },
  "ttlSeconds": 300,
  "metadata": {
    "worker": "api-eu-1"
  },
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

JSON

{
  "id": "lease_01m4v0d9k2j7r5t3w8x6y4z2b0",
  "object": "lease",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "walletId": "wal_01m4ty3c2b5qx7mhd9k8w6s0b1",
  "status": "active",
  "amount": {
    "amount": "5000000",
    "currency": "EUR"
  },
  "captured": {
    "amount": "0",
    "currency": "EUR"
  },
  "remaining": {
    "amount": "5000000",
    "currency": "EUR"
  },
  "ttlSeconds": 300,
  "expiresAt": "2026-10-13T12:05:00.000Z",
  "expiryPolicy": "release",
  "lateSettleWindowSeconds": null,
  "lateSettleFallback": null,
  "lateSettleUntil": null,
  "settleSeq": 0,
  "renewedFrom": null,
  "renewedTo": null,
  "suggestedNextAmount": {
    "amount": "5000000",
    "currency": "EUR"
  },
  "metadata": {
    "worker": "api-eu-1"
  },
  "createdAt": "2026-10-13T12:00:00.000Z",
  "closedAt": null
}

A lease that survives a crash

The funds stay reserved for an hour after the TTL, for one late settle; then they're released.

Arguments:

JSON

{
  "id": "wal_01m4ty3c2b5qx7mhd9k8w6s0b1",
  "amount": {
    "amount": "5000000",
    "currency": "EUR"
  },
  "ttlSeconds": 300,
  "expiryPolicy": "hold_for_late_settle",
  "lateSettleWindowSeconds": 3600,
  "metadata": {
    "worker": "api-eu-1"
  },
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

JSON

{
  "id": "lease_01m4v0d9k2j7r5t3w8x6y4z2b0",
  "object": "lease",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "walletId": "wal_01m4ty3c2b5qx7mhd9k8w6s0b1",
  "status": "active",
  "amount": {
    "amount": "5000000",
    "currency": "EUR"
  },
  "captured": {
    "amount": "0",
    "currency": "EUR"
  },
  "remaining": {
    "amount": "5000000",
    "currency": "EUR"
  },
  "ttlSeconds": 300,
  "expiresAt": "2026-10-13T12:05:00.000Z",
  "expiryPolicy": "hold_for_late_settle",
  "lateSettleWindowSeconds": 3600,
  "lateSettleFallback": "release",
  "lateSettleUntil": "2026-10-13T13:05:00.000Z",
  "settleSeq": 0,
  "renewedFrom": null,
  "renewedTo": null,
  "suggestedNextAmount": {
    "amount": "5000000",
    "currency": "EUR"
  },
  "metadata": {
    "worker": "api-eu-1"
  },
  "createdAt": "2026-10-13T12:00:00.000Z",
  "closedAt": null
}

`leases_get`

Get a lease. Operation leases.get · Brand level · permission wallets:read · risk tier read · since M6

Returns a lease: how much was leased (amount), what its settles have charged (captured), what can still be consumed (remaining), its status, expiresAt and expiry terms, its settleSeq (the number of settles so far), the leases it renewed or was renewed into, and suggestedNextAmount, sizing guidance for the next lease from the recent consumption rate.

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments

Argument	Type	Required	Description
`id`	ID (`lease_…`)	yes	The lease (`lease_…`).
`entity_id`	ID (`ent_…`)	no	Optional: the brand's legal entity (ent_…); `brand_id` alone is enough.
`brand_id`	ID (`brd_…`)	no	The brand to act on (brd_…), inside your API key's reach. Needed with an organization or entity key; a brand key acts on its own brand.

Brand: pass brand_id with an organization or entity key; a brand key acts on its own brand.
Read-only: changes nothing; idempotency_key is ignored.

Errors

resource_not_found: No lease with this ID in the brand and mode.
permission_denied: The credentials can't read this brand's wallets (wallets:read).

Example

A lease after one settle

Arguments:

JSON

{
  "id": "lease_01m4v0d9k2j7r5t3w8x6y4z2b0",
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz"
}

Result output:

JSON

{
  "id": "lease_01m4v0d9k2j7r5t3w8x6y4z2b0",
  "object": "lease",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "livemode": false,
  "walletId": "wal_01m4ty3c2b5qx7mhd9k8w6s0b1",
  "status": "active",
  "amount": {
    "amount": "5000000",
    "currency": "EUR"
  },
  "captured": {
    "amount": "1250000",
    "currency": "EUR"
  },
  "remaining": {
    "amount": "3750000",
    "currency": "EUR"
  },
  "ttlSeconds": 300,
  "expiresAt": "2026-10-13T12:05:00.000Z",
  "expiryPolicy": "release",
  "lateSettleWindowSeconds": null,
  "lateSettleFallback": null,
  "lateSettleUntil": null,
  "settleSeq": 1,
  "renewedFrom": null,
  "renewedTo": null,
  "suggestedNextAmount": {
    "amount": "7812500",
    "currency": "EUR"
  },
  "metadata": {
    "worker": "api-eu-1"
  },
  "createdAt": "2026-10-13T12:00:00.000Z",
  "closedAt": null
}

`leases_settle`

Settle a lease. Operation leases.settle · Brand level · permission wallets:write · risk tier write · since M6

Charges what your service consumed from a lease since the previous settle (consumed), with a usageSummary: one line per meter (and attribute set) with the quantity used and its amount; the amounts add up to consumed. Each line is stored as a usage event and counted in the daily usage aggregates. The settle is charged at once (the lease's captured grows); the ledger books what a lease's settles charged as usage revenue per meter in one posting, when the lease closes, is renewed or expires. Wallet usage can't use a meter that a metered price bills in arrears (prepaid and arrears usage coexist on different meters).

Then the lease:

stays open (neither final nor renew): keep consuming its remaining;
closes (final: true): what it still holds goes back to the wallet;
is renewed (renew): it closes, and a new lease with a new ID, a fresh TTL and the same expiry terms is reserved, for renew.amount (default: the same amount) or as much of it as the wallet has. renewedLease is null when the wallet can't fund it.

A settle after expiresAt gets lease_expired, except within the late-settle window of a hold_for_late_settle lease: that settle charges consumed and closes the lease (late: true).

Ordering and retries: a resent settle (same Idempotency-Key and content) is answered with duplicate: true and changes nothing. Optionally number your settles with settleSeq (the lease's settleSeq plus one): a numbered settle is applied only after the one before it (lease_settle_out_of_order, retryable, otherwise), so a final settle can't overtake earlier usage, and a settle numbered at or below the lease's settleSeq is a duplicate. Every response has the lease's suggestedNextAmount.

Annotations: readOnlyHint: false · destructiveHint: true · idempotentHint: true · openWorldHint: false

Arguments

Argument	Type	Required	Description
`id`	ID (`lease_…`)	yes	The lease (`lease_…`).
`consumed`	object	yes	What was used since the previous settle of this lease, in its currency; at most what it still holds.
`usageSummary`	array of object	no	Up to 100 lines, one per meter (and attribute set), whose amounts add up to `consumed`. Each is stored as a usage event. (at most 100 items)
`final`	boolean	no	true: close the lease; what it still holds goes back to the wallet.
`renew`	object	no	Close this lease and continue in a new one (new ID, fresh TTL, same expiry terms). Send `{}` to keep the amount and TTL.
`settleSeq`	integer	no	Optional: this settle's number, the lease's `settleSeq` plus one. Numbered settles are applied in order, and a resent one is answered as a duplicate. (1–9007199254740991)
`entity_id`	ID (`ent_…`)	no	Optional: the brand's legal entity (ent_…); `brand_id` alone is enough.
`brand_id`	ID (`brd_…`)	no	The brand to act on (brd_…), inside your API key's reach. Needed with an organization or entity key; a brand key acts on its own brand.
`idempotency_key`	string	no	A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters)
`dry_run`	boolean	no	true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)

Brand: pass brand_id with an organization or entity key; a brand key acts on its own brand.
Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.

Errors

validation_failed: A field is malformed, or a settle asks for both final and renew.
lease_usage_mismatch: The amounts of the usageSummary lines don't add up to consumed.
capture_exceeds_reservation: consumed is more than the lease still holds (remaining).
wallet_currency_mismatch: consumed isn't in the lease's currency.
usage_meter_billed_in_arrears: A line names a meter a metered price bills in arrears.
resource_not_found: No lease with this ID in the brand and mode.
lease_expired: The lease is past expiresAt (and past lateSettleUntil for hold_for_late_settle).
lease_closed: A final settle or a renewal already closed the lease (details.renewedTo names its successor).
lease_settle_out_of_order: settleSeq skips a settle that hasn't arrived yet (retryable).
lease_settle_seq_conflict: The lease's last settle has this settleSeq but other content.
idempotency_key_reused: The Idempotency-Key was already used for a different settle of this lease.
permission_denied: The credentials can't use this brand's wallets (wallets:write).

Examples

Settle usage of two meters and keep the lease

Arguments:

JSON

{
  "id": "lease_01m4v0d9k2j7r5t3w8x6y4z2b0",
  "consumed": {
    "amount": "1250000",
    "currency": "EUR"
  },
  "usageSummary": [
    {
      "meter": "api.calls",
      "quantity": "1000",
      "amount": {
        "amount": "1000000",
        "currency": "EUR"
      },
      "attributes": {
        "model": "large"
      }
    },
    {
      "meter": "tokens.out",
      "quantity": "25000",
      "amount": {
        "amount": "250000",
        "currency": "EUR"
      }
    }
  ],
  "settleSeq": 1,
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

JSON

{
  "object": "lease_settlement",
  "settleSeq": 1,
  "duplicate": false,
  "late": false,
  "consumed": {
    "amount": "1250000",
    "currency": "EUR"
  },
  "lease": {
    "id": "lease_01m4v0d9k2j7r5t3w8x6y4z2b0",
    "object": "lease",
    "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
    "livemode": false,
    "walletId": "wal_01m4ty3c2b5qx7mhd9k8w6s0b1",
    "status": "active",
    "amount": {
      "amount": "5000000",
      "currency": "EUR"
    },
    "captured": {
      "amount": "1250000",
      "currency": "EUR"
    },
    "remaining": {
      "amount": "3750000",
      "currency": "EUR"
    },
    "ttlSeconds": 300,
    "expiresAt": "2026-10-13T12:05:00.000Z",
    "expiryPolicy": "release",
    "lateSettleWindowSeconds": null,
    "lateSettleFallback": null,
    "lateSettleUntil": null,
    "settleSeq": 1,
    "renewedFrom": null,
    "renewedTo": null,
    "suggestedNextAmount": {
      "amount": "7812500",
      "currency": "EUR"
    },
    "metadata": {
      "worker": "api-eu-1"
    },
    "createdAt": "2026-10-13T12:00:00.000Z",
    "closedAt": null
  },
  "renewedLease": null,
  "usageEventIds": ["uev_01m4v0d9k2j7r5t3w8x6y4z2b2", "uev_01m4v0d9k2j7r5t3w8x6y4z2b3"]
}

Settle and renew before the TTL

The lease closes and a new 5.00 lease continues with a fresh TTL.

Arguments:

JSON

{
  "id": "lease_01m4v0d9k2j7r5t3w8x6y4z2b0",
  "consumed": {
    "amount": "3500000",
    "currency": "EUR"
  },
  "usageSummary": [
    {
      "meter": "api.calls",
      "quantity": "3500",
      "amount": {
        "amount": "3500000",
        "currency": "EUR"
      }
    }
  ],
  "renew": {},
  "settleSeq": 2,
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

JSON

{
  "object": "lease_settlement",
  "settleSeq": 2,
  "duplicate": false,
  "late": false,
  "consumed": {
    "amount": "3500000",
    "currency": "EUR"
  },
  "lease": {
    "id": "lease_01m4v0d9k2j7r5t3w8x6y4z2b0",
    "object": "lease",
    "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
    "livemode": false,
    "walletId": "wal_01m4ty3c2b5qx7mhd9k8w6s0b1",
    "status": "captured",
    "amount": {
      "amount": "5000000",
      "currency": "EUR"
    },
    "captured": {
      "amount": "4750000",
      "currency": "EUR"
    },
    "remaining": {
      "amount": "0",
      "currency": "EUR"
    },
    "ttlSeconds": 300,
    "expiresAt": "2026-10-13T12:05:00.000Z",
    "expiryPolicy": "release",
    "lateSettleWindowSeconds": null,
    "lateSettleFallback": null,
    "lateSettleUntil": null,
    "settleSeq": 2,
    "renewedFrom": null,
    "renewedTo": "lease_01m4v0d9k2j7r5t3w8x6y4z2b1",
    "suggestedNextAmount": {
      "amount": "7421875",
      "currency": "EUR"
    },
    "metadata": {
      "worker": "api-eu-1"
    },
    "createdAt": "2026-10-13T12:00:00.000Z",
    "closedAt": "2026-10-13T12:04:00.000Z"
  },
  "renewedLease": {
    "id": "lease_01m4v0d9k2j7r5t3w8x6y4z2b1",
    "object": "lease",
    "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
    "livemode": false,
    "walletId": "wal_01m4ty3c2b5qx7mhd9k8w6s0b1",
    "status": "active",
    "amount": {
      "amount": "5000000",
      "currency": "EUR"
    },
    "captured": {
      "amount": "0",
      "currency": "EUR"
    },
    "remaining": {
      "amount": "5000000",
      "currency": "EUR"
    },
    "ttlSeconds": 300,
    "expiresAt": "2026-10-13T12:09:00.000Z",
    "expiryPolicy": "release",
    "lateSettleWindowSeconds": null,
    "lateSettleFallback": null,
    "lateSettleUntil": null,
    "settleSeq": 0,
    "renewedFrom": "lease_01m4v0d9k2j7r5t3w8x6y4z2b0",
    "renewedTo": null,
    "suggestedNextAmount": {
      "amount": "7421875",
      "currency": "EUR"
    },
    "metadata": {
      "worker": "api-eu-1"
    },
    "createdAt": "2026-10-13T12:04:00.000Z",
    "closedAt": null
  },
  "usageEventIds": ["uev_01m4v0d9k2j7r5t3w8x6y4z2b2"]
}

Close the lease

Arguments:

JSON

{
  "id": "lease_01m4v0d9k2j7r5t3w8x6y4z2b0",
  "consumed": {
    "amount": "0",
    "currency": "EUR"
  },
  "usageSummary": [],
  "final": true,
  "brand_id": "brd_01jbx4m3v8e9t0s6k2c5n7q1wz",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

JSON

{
  "object": "lease_settlement",
  "settleSeq": 1,
  "duplicate": false,
  "late": false,
  "consumed": {
    "amount": "0",
    "currency": "EUR"
  },
  "lease": {
    "id": "lease_01m4v0d9k2j7r5t3w8x6y4z2b0",
    "object": "lease",
    "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
    "livemode": false,
    "walletId": "wal_01m4ty3c2b5qx7mhd9k8w6s0b1",
    "status": "captured",
    "amount": {
      "amount": "5000000",
      "currency": "EUR"
    },
    "captured": {
      "amount": "0",
      "currency": "EUR"
    },
    "remaining": {
      "amount": "0",
      "currency": "EUR"
    },
    "ttlSeconds": 300,
    "expiresAt": "2026-10-13T12:05:00.000Z",
    "expiryPolicy": "release",
    "lateSettleWindowSeconds": null,
    "lateSettleFallback": null,
    "lateSettleUntil": null,
    "settleSeq": 1,
    "renewedFrom": null,
    "renewedTo": null,
    "suggestedNextAmount": {
      "amount": "500000",
      "currency": "EUR"
    },
    "metadata": {
      "worker": "api-eu-1"
    },
    "createdAt": "2026-10-13T12:00:00.000Z",
    "closedAt": "2026-10-13T12:01:00.000Z"
  },
  "renewedLease": null,
  "usageEventIds": []
}

leases_create#

Arguments#

Errors#

Examples#

leases_get#

Arguments#

Errors#

Example#

leases_settle#

Arguments#

Errors#

Examples#

`leases_create`

Arguments

Errors

Examples

`leases_get`

Arguments

Errors

Example

`leases_settle`

Arguments

Errors

Examples