# Holds

Place, capture, and release authorization holds against an account's available balance.

URL: https://docs.shiwake.app/docs/api/holds



A **hold** is a reservation against an account's available balance. It does
not move money (the ledger balance is unchanged) but it reduces the amount
available for new debits. Holds let you authorize a transaction now and
settle it later, or authorize an amount and settle the final value once it's
known.

Lifecycle [#lifecycle]

A hold is created in `Active` status and ends up in one of three terminal
states:

| Status     | How it gets there                                       |
| ---------- | ------------------------------------------------------- |
| `Active`   | Just placed, not yet captured or released               |
| `Captured` | Caller posted the settling journal entry: balance moves |
| `Released` | Caller abandoned the hold: available balance restored   |
| `Expired`  | `expiresAt` passed; treated like a release              |

Only active holds count against available balance. Once captured or
released, they no longer reduce availability.

<Callout type="info">
  `ledger_balance − Σ(active holds) = available_balance`. See [Accounts](/docs/api/accounts)
  for the two balance concepts.
</Callout>

The Hold object [#the-hold-object]

```json
{
  "id": "hld_01HZ...",
  "accountId": "acc_01HZ...",
  "amountMinor": 25000,
  "currency": "GHS",
  "reference": "auth_01J...",
  "status": "Active",
  "journalEntryId": null,
  "metadata": { "order": "ord_4821" },
  "expiresAt": "2026-04-08T12:00:00Z",
  "createdBy": "checkout-service",
  "createdAt": "2026-04-07T12:00:00Z"
}
```

<TypeTable
  type="{
  id: { type: &#x22;string&#x22;, required: true, description: <>ULID, prefixed <code>hld_</code></> },
  accountId: { type: &#x22;string&#x22;, required: true, description: &#x22;Account the hold is placed on&#x22; },
  amountMinor: { type: &#x22;long&#x22;, required: true, description: &#x22;Reserved amount in minor units&#x22; },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;ISO 4217 code&#x22; },
  reference: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Client-supplied correlation id&#x22; },
  status: { type: &#x22;string&#x22;, required: true, description: <><code>Active</code>, <code>Captured</code>, <code>Released</code>, <code>Expired</code></> },
  journalEntryId: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Set when the hold is captured&#x22; },
  metadata: { type: &#x22;object | null&#x22;, required: true, description: &#x22;Arbitrary JSON&#x22; },
  expiresAt: { type: &#x22;datetime | null&#x22;, required: true, description: &#x22;When the hold auto-expires&#x22; },
  createdAt: { type: &#x22;datetime&#x22;, required: true, description: &#x22;Creation timestamp&#x22; },
}"
/>

***

Place a hold [#place-a-hold]

<Endpoint method="POST" path="/api/v1/ledger/holds" />

Reserves `amountMinor` on an account. The account's ledger balance does not
change. Fails with `422` if the available balance is insufficient.

Request body [#request-body]

<TypeTable
  type="{
  accountId: { type: &#x22;string&#x22;, required: true, description: &#x22;Account to place the hold on&#x22; },
  amountMinor: { type: &#x22;long&#x22;, required: true, description: &#x22;Amount to reserve, in minor units&#x22; },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;Must match the account's currency&#x22; },
  reference: { type: &#x22;string&#x22;, description: &#x22;Correlation id for your system&#x22; },
  createdBy: { type: &#x22;string&#x22;, description: &#x22;Free-form actor identifier&#x22; },
  expiresAt: { type: &#x22;datetime&#x22;, description: &#x22;ISO 8601, UTC. Omit for open-ended&#x22; },
  metadata: { type: &#x22;object&#x22;, description: &#x22;Arbitrary JSON&#x22; },
}"
/>

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="csharp">
      C# (SDK)
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl -X POST "https://api.shiwake.example.com/api/v1/ledger/holds" \
      -H "X-Api-Key: sk_live_..." \
      -H "Idempotency-Key: 8b7f9c2e-4d1a-4e6b-9c3a-1f2e3d4c5b6a" \
      -H "Content-Type: application/json" \
      -d '{
        "accountId": "acc_01HZ...",
        "amountMinor": 25000,
        "currency": "GHS",
        "reference": "auth_01J...",
        "createdBy": "checkout-service",
        "expiresAt": "2026-04-08T12:00:00Z"
      }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="csharp">
    ```csharp
    var hold = await ledger.PlaceHoldAsync(new PlaceHoldRequest
    {
        AccountId   = "acc_01HZ...",
        AmountMinor = 25_000,
        Currency    = "GHS",
        Reference   = "auth_01J...",
        CreatedBy   = "checkout-service",
        ExpiresAt   = DateTime.UtcNow.AddHours(24)
    }, idempotencyKey: Guid.NewGuid().ToString());
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 201,
      "message": "Hold placed.",
      "data": {
        "id": "hld_01HZ...",
        "accountId": "acc_01HZ...",
        "amountMinor": 25000,
        "currency": "GHS",
        "reference": "auth_01J...",
        "status": "Active",
        "journalEntryId": null,
        "metadata": null,
        "expiresAt": "2026-04-08T12:00:00Z",
        "createdBy": "checkout-service",
        "createdAt": "2026-04-07T12:00:00Z"
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Status codes [#status-codes]

| Code  | When                                              |
| ----- | ------------------------------------------------- |
| `201` | Hold placed                                       |
| `400` | Missing `Idempotency-Key`, invalid body           |
| `404` | Account does not exist                            |
| `422` | Insufficient available balance, currency mismatch |

***

Capture a hold [#capture-a-hold]

<Endpoint method="POST" path="/api/v1/ledger/holds/{holdId}/capture" />

Settles an active hold by posting a journal entry. The entry's lines must
balance per the usual double-entry rules (see [Journal Entries](/docs/api/journal-entries)).
The captured amount can be less than the original hold. The remainder is
released automatically.

Request body [#request-body-1]

<TypeTable
  type="{
  description: { type: &#x22;string&#x22;, description: &#x22;Journal entry description&#x22; },
  createdBy: { type: &#x22;string&#x22;, description: &#x22;Actor identifier&#x22; },
  lines: { type: &#x22;array&#x22;, required: true, description: &#x22;Entry lines for the settling journal entry&#x22; },
}"
/>

Each line has `accountCode`, `entryType` (`Debit` or `Credit`), `amount`, and
optional `description`: identical to a normal journal entry line.

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="csharp">
      C# (SDK)
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl -X POST "https://api.shiwake.example.com/api/v1/ledger/holds/hld_01HZ.../capture" \
      -H "X-Api-Key: sk_live_..." \
      -H "Idempotency-Key: 9c8f0d3f-5e2b-4f7c-ad4b-2e3f4d5c6b7c" \
      -H "Content-Type: application/json" \
      -d '{
        "description": "Order ord_4821 settlement",
        "createdBy": "checkout-service",
        "lines": [
          { "accountCode": "CLIENT-42",      "entryType": "Debit",  "amount": 22500 },
          { "accountCode": "PLATFORM-FLOAT", "entryType": "Credit", "amount": 22500 }
        ]
      }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="csharp">
    ```csharp
    var capture = await ledger.CaptureHoldAsync(
        holdId: "hld_01HZ...",
        new CaptureHoldRequest
        {
            Description = "Order ord_4821 settlement",
            CreatedBy   = "checkout-service",
            Lines =
            [
                new("CLIENT-42",      EntryType.Debit,  22_500),
                new("PLATFORM-FLOAT", EntryType.Credit, 22_500)
            ]
        },
        idempotencyKey: Guid.NewGuid().ToString());
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 200,
      "message": "Hold captured.",
      "data": {
        "journalEntryId": "jen_01HZ...",
        "holdId": "hld_01HZ...",
        "holdStatus": "Captured",
        "reference": "auth_01J...",
        "postedAt": "2026-04-07T12:05:00Z"
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Status codes [#status-codes-1]

| Code  | When                                                                   |
| ----- | ---------------------------------------------------------------------- |
| `200` | Hold captured; journal entry posted                                    |
| `400` | Missing `Idempotency-Key`, invalid body                                |
| `404` | Hold does not exist                                                    |
| `409` | Hold is not in `Active` status (already captured/released/expired)     |
| `422` | Capture amount exceeds hold, lines don't balance, insufficient balance |

***

Release a hold [#release-a-hold]

<Endpoint method="POST" path="/api/v1/ledger/holds/{holdId}/release" />

Abandons an active hold without posting an entry. The reserved amount
returns to available balance immediately. Releasing is the right call when
an authorization is cancelled before settlement.

Request body [#request-body-2]

<TypeTable
  type="{
  reason: { type: &#x22;string&#x22;, description: &#x22;Free-form reason, stored with the hold&#x22; },
}"
/>

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="csharp">
      C# (SDK)
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl -X POST "https://api.shiwake.example.com/api/v1/ledger/holds/hld_01HZ.../release" \
      -H "X-Api-Key: sk_live_..." \
      -H "Idempotency-Key: ad9e1f4a-6f3c-5a8d-be5c-3f4e5d6c7b8d" \
      -H "Content-Type: application/json" \
      -d '{ "reason": "Customer cancelled order" }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="csharp">
    ```csharp
    await ledger.ReleaseHoldAsync(
        holdId: "hld_01HZ...",
        reason: "Customer cancelled order",
        idempotencyKey: Guid.NewGuid().ToString());
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 200,
      "message": "Hold released.",
      "data": {
        "id": "hld_01HZ...",
        "status": "Released",
        "amountMinor": 25000,
        "currency": "GHS"
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Status codes [#status-codes-2]

| Code  | When                           |
| ----- | ------------------------------ |
| `200` | Hold released                  |
| `404` | Hold does not exist            |
| `409` | Hold is not in `Active` status |

***

List holds on an account [#list-holds-on-an-account]

<Endpoint method="GET" path="/api/v1/ledger/accounts/{accountId}/holds" />

Returns holds for a specific account, newest first. Paginated with cursor
format `createdAt|id`. See [Pagination](/docs/api/pagination).

Query parameters [#query-parameters]

<TypeTable
  type="{
  status: { type: &#x22;string&#x22;, description: <>Filter by <code>Active</code>, <code>Captured</code>, <code>Released</code>, <code>Expired</code></> },
  cursor: { type: &#x22;string&#x22;, description: &#x22;Pagination cursor&#x22; },
  size: { type: &#x22;int&#x22;, description: <>Page size, default <code>50</code>, max <code>200</code></> },
}"
/>

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="csharp">
      C# (SDK)
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl "https://api.shiwake.example.com/api/v1/ledger/accounts/acc_01HZ.../holds?status=Active&size=20" \
      -H "X-Api-Key: sk_live_..."
    ```
  </CodeBlockTab>

  <CodeBlockTab value="csharp">
    ```csharp
    var page = await ledger.ListHoldsAsync(
        accountId: "acc_01HZ...",
        status:    HoldStatus.Active,
        size:      20);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 200,
      "message": "Retrieved successfully",
      "data": {
        "account_id": "acc_01HZ...",
        "holds": [
          {
            "id": "hld_01HZ...",
            "accountId": "acc_01HZ...",
            "amountMinor": 25000,
            "currency": "GHS",
            "status": "Active",
            "createdAt": "2026-04-07T12:00:00Z"
          }
        ],
        "next_cursor": null
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>
