# Capture a reservation > The reservations.capture operation: POST /api/v1/reservations/{id}/capture in the REST API and the reservations_capture tool in the MCP server. Charges what was used from a reservation: at most what is still reserved (`capture_exceeds_reservation`), and before `expiresAt` (`reservation_expired`). By default the rest is released and the reservation closes as `captured`; with `final: false` it stays open for further captures until it expires. `usage` says what the amount was spent on, one line per meter (`meter`, `quantity`, `amount`, `attributes`); the line amounts add up to `amount`. The revenue is booked per meter, and each line is stored as a usage event (with its wallet, the reservation and its amount) and counted in the daily usage aggregates. A meter that a metered price bills in arrears can't be used (`usage_meter_billed_in_arrears`). Without `usage` the whole amount is usage of the meter `default`, and no usage event is stored. The captured credits leave the wallet: it may emit `wallet.low_balance` or `wallet.depleted`, and start an auto-reload. The same `idempotencyKey` (or `Idempotency-Key`) and request returns the same capture. ## At a glance - **REST:** `POST /api/v1/reservations/{id}/capture` - **MCP tool:** `reservations_capture` - **Operation ID:** `reservations.capture` - **Scope:** Brand - **Permission:** `wallets:write` - **Risk tier:** `write` - **Dry run:** Supported (send `Ownrecord-Dry-Run: true`) - **Idempotency:** `Idempotency-Key` required - **Modes:** Test and live - **Authentication:** API key with the `wallets:write` scope - **Since:** M6 ## Request ### Path parameters | Field | Type | Description | | ----- | ---------- | -------------------------- | | `id` | `res_…` ID | The reservation (`res_…`). | ### Body A JSON object (`Content-Type: application/json`): | Field | Type | Required | Description | | ------------------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `amount` | object | Yes | What was used: at most what is still reserved. | | `amount.amount` | string | Yes | Integer micros as a string (5000000 = 5.00). | | `amount.currency` | string | Yes | ISO 4217 currency code: the wallet's currency. | | `usage` | array of object | No | What the amount was spent on, one line per meter. Without it the whole amount is usage of the meter `default`. | | `usage[].meter` | string | Yes | What was used, e.g. `api.calls`: the revenue goes to this meter. | | `usage[].quantity` | string | Yes | How much of the meter was used, as an integer string. | | `usage[].amount` | object | Yes | What this line costs, in the wallet's currency. The lines add up to the capture's `amount`. | | `usage[].amount.amount` | string | Yes | | | `usage[].amount.currency` | string | Yes | | | `usage[].attributes` | object | No | Optional dimensions of the event, e.g. `{ "model": "large" }`; usage is aggregated per day and attribute set. | | `final` | boolean | No | Release the rest and close the reservation (default `true`). `false` keeps it open for more captures until it expires. | | `idempotencyKey` | string | No | Unique per reservation: the same key and request returns the same capture (default: the request's `Idempotency-Key`). | ## Response `200 OK` with a JSON object: | Field | Type | Description | | ---------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | `id` | string | | | `object` | `"reservation"` | | | `brandId` | `brd_…` ID | | | `livemode` | boolean | | | `walletId` | `wal_…` ID | | | `kind` | one of `single`, `lease` | `single` (§17.2) or `lease` (§17.3). | | `status` | one of `active`, `expired_pending`, `captured`, `released`, `expired` | `active`, `captured`, `released`, `expired` (or `expired_pending` for leases). | | `amount` | money | What was reserved. | | `captured` | money | What was captured so far. | | `outstanding` | money | What is still held: `amount − captured` while open, zero once closed. | | `expiresAt` | date-time | | | `closedAt` | date-time or null | | | `idempotencyKey` | string | | | `metadata` | object | | | `createdAt` | date-time | | | `updatedAt` | date-time | | ## Examples ### Capture €1.25 of €3 for 250 API calls and release the rest ```http POST /api/v1/reservations/res_01m4ty7w2a5qx7mhd9k8w6s0b4/capture Authorization: Bearer or_test_… Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14 Content-Type: application/json { "amount": { "amount": "1250000", "currency": "EUR" }, "usage": [ { "meter": "api.calls", "quantity": "250", "amount": { "amount": "1250000", "currency": "EUR" } } ] } ``` Response (`200`): ```json { "id": "res_01m4ty7w2a5qx7mhd9k8w6s0b4", "object": "reservation", "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "livemode": false, "walletId": "wal_01m4ty7w2a5qx7mhd9k8w6s0b1", "kind": "single", "status": "captured", "amount": { "amount": "3000000", "currency": "EUR" }, "captured": { "amount": "1250000", "currency": "EUR" }, "outstanding": { "amount": "0", "currency": "EUR" }, "expiresAt": "2026-10-16T10:20:00.000Z", "closedAt": "2026-10-16T10:16:00.000Z", "idempotencyKey": "job-8841", "metadata": { "job": "8841" }, "createdAt": "2026-10-16T10:15:00.000Z", "updatedAt": "2026-10-16T10:16:00.000Z" } ``` ## Errors | Code | HTTP status | When | What to do | | -------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | The amount isn't positive, or the usage lines don't add up to it or are malformed. | Fix the fields listed in `details.issues` and send the request again. | | [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found) | 404 | This brand has no such reservation in this mode. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. | | [`capture_exceeds_reservation`](https://ownrecord.io/docs/reference/errors.md#capture_exceeds_reservation) | 400 | The amount is more than is still reserved (`details.outstanding`). | Capture at most the reserved amount that is still open (`details.outstanding`, integer micros), or reserve more first. | | [`reservation_expired`](https://ownrecord.io/docs/reference/errors.md#reservation_expired) | 409 | The reservation's `expiresAt` has passed: reserve again. | Reserve the amount again and capture the new reservation. Expired reservations are released automatically. | | [`reservation_not_open`](https://ownrecord.io/docs/reference/errors.md#reservation_not_open) | 409 | The reservation was already captured, released or expired. | Create a new reservation. A reservation is closed once it is captured, released or expired (`details.status`). | | [`wallet_currency_mismatch`](https://ownrecord.io/docs/reference/errors.md#wallet_currency_mismatch) | 400 | The amount or a usage line isn't in the wallet's currency. | Use the wallet for this currency. A customer has one wallet per currency (`details.expected`, `details.actual`). | | [`usage_meter_billed_in_arrears`](https://ownrecord.io/docs/reference/errors.md#usage_meter_billed_in_arrears) | 400 | A usage line names a meter a metered price bills in arrears (prepaid usage needs another meter). | Report prepaid (wallet) usage on a meter that no metered price names, e.g. `api.calls.prepaid` (`details.meter`). | | [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused) | 409 | The idempotency key was used before for another request. | Use a new Idempotency-Key for a different request, or resend the original request unchanged. | | [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict) | 409 | The wallet changed at the same moment (another reservation, capture or grant); retry. | Fetch the object again and retry the change. | | [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required) | 400 | The request names no brand (an org or entity key without `Ownrecord-Brand`). | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`). | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't change this brand's wallets (`wallets:write`: owners, admins and support). | Ask an organization owner or admin for a role or scope that allows this action. | | [`livemode_not_allowed`](https://ownrecord.io/docs/reference/errors.md#livemode_not_allowed) | 403 | You have no live-mode access, so you can't use live wallets. | Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin. | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).