---
title: "Capture a credit hold"
description: "Records the real usage and closes the hold in one step: send the usage event itself (usage_event, the body of POST …/usage_events) or the key of one already sent (usage_event_id)."
canonical_url: "https://twominutebilling.com/help/developers/api-reference/credits/capture-a-credit-hold"
---
# Capture a credit hold

> Records the real usage and closes the hold in one step: send the usage event itself (usage_event, the body of POST …/usage_events) or the key of one already sent (usage_event_id).

<api-operation method="POST" path="/v1/businesses/{biz}/credit_holds/{hold}/capture">
<template v-slot:docs="">

Records the real usage and closes the hold in one step: send the usage event itself (`usage_event`, the body of `POST …/usage_events`) or the `key` of one already sent (`usage_event_id`). The hold stops counting and the event starts counting together. Usage above the hold is accepted; past the overdraft limit the hold is marked `overdraft` and the rest bills on the next invoice. Needs `credit_holds:manage`.

## Path parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        biz
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      The business's id (biz_…).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        hold
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      The credit hold's id (chd_…).
    </td>
  </tr>
</tbody>
</table>

## Headers

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Idempotency-Key
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      Safely retry writes — repeats return the original response. If a write FAILED after it had already taken effect, that failure is what repeats: the key is spent, and a new attempt needs a new key.
    </td>
  </tr>
</tbody>
</table>

## Body

The request body is **required**.

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        usage_event
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      A usage event to record now.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        usage_event_id
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      no
    </td>
    
    <td>
      The <code>
        key
      </code>
      
       of a usage event that you already sent.
    </td>
  </tr>
</tbody>
</table>

## Response

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The object type; always <code>
        credit_hold
      </code>
      
      . One of <code>
        credit_hold
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      chd_…
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        customer
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      cus_…
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        currency
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      ISO 4217.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        amount_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      The amount held.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        meter
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The meter's id.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        scope
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Usage property values, for scoped spend limits.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        status
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The credit hold's status. One of <code>
        held
      </code>
      
      , <code>
        captured
      </code>
      
      , <code>
        released
      </code>
      
      , <code>
        expired
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        expires_at
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      When the credit hold expires (ISO-8601 UTC).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        captured_minor
      </code>
    </td>
    
    <td>
      <code>
        integer
      </code>
    </td>
    
    <td>
      The rated value of the captured usage event.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        overdraft
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      The captured usage took the balance past the overdraft limit.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata
      </code>
    </td>
    
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      Key-value pairs you attach to the credit hold.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        created_at
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      When the credit hold was created (ISO-8601 UTC).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        updated_at
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      When the credit hold was last changed (ISO-8601 UTC).
    </td>
  </tr>
</tbody>
</table>

## Status codes

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        200
      </code>
    </td>
    
    <td>
      The captured hold.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        400
      </code>
    </td>
    
    <td>
      The body is not correct.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        404
      </code>
    </td>
    
    <td>
      No such credit hold.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        409
      </code>
    </td>
    
    <td>
      The hold is already captured, released or expired.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        422
      </code>
    </td>
    
    <td>
      The usage event was refused.
    </td>
  </tr>
</tbody>
</table>
</template>

<template v-slot:request="">

```bash [Request]
curl -X POST "$TMBILLING_URL/v1/businesses/biz_XXXXXXXXXXXX01/credit_holds/chd_XXXXXXXXXXXX01/capture" \
  -H "Authorization: Bearer $TMBILLING_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "usage_event_id": "evt_XXXXXXXXXXXX01"
  }'
```

</template>

<template v-slot:response="">
<code-group>

```json [200 OK]
{
  "object": "credit_hold",
  "id": "chd_XXXXXXXXXXXX01",
  "customer": "cus_XXXXXXXXXXXX01",
  "currency": "USD",
  "amount_minor": 2900,
  "meter": "Meter",
  "scope": {},
  "status": "held",
  "expires_at": "2026-04-14T09:30:00Z",
  "captured_minor": 2900,
  "overdraft": false,
  "metadata": {
    "crm_id": "acct-1001"
  },
  "created_at": "2026-03-14T09:30:00Z",
  "updated_at": "2026-03-14T09:30:00Z"
}
```

```json [400 Bad Request]
{
  "error": {
    "type": "invalid_request_error",
    "message": "The body is not correct."
  }
}
```

```json [404 Not Found]
{
  "error": {
    "type": "invalid_request_error",
    "message": "No such credit hold."
  }
}
```

```json [409 Conflict]
{
  "error": {
    "type": "conflict_error",
    "message": "The hold is already captured, released or expired."
  }
}
```

```json [422 Unprocessable Entity]
{
  "error": {
    "type": "invalid_request_error",
    "message": "The usage event was refused."
  }
}
```

</code-group>
</template>
</api-operation>


## Sitemap

See the full [sitemap](https://twominutebilling.com/sitemap.md) for all pages.