> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nedzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Debit wallet

> Deduct funds from a workspace wallet as a manual adjustment via the Nedzo REST API. Returns 402 if the balance is insufficient for the debit.

<ParamField path="workspaceId" type="string" required>
  Workspace UUID
</ParamField>

<ParamField body="amount" type="integer" required>
  Amount to debit in cents. Must be a positive integer.
</ParamField>

<ParamField body="reason" type="string" required>
  Human-readable reason for the adjustment (1-500 characters). Cannot contain the substring `[idempotency:`.
</ParamField>

<ParamField body="idempotencyKey" type="string">
  Optional idempotency key (a-z, A-Z, 0-9, hyphen, 1-128 chars). If provided, a retry with the same key within 24 hours returns the existing transaction without re-applying the debit.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.nedzo.ai/v1/workspaces/19c3b12f-ec54-43ad-8686-00e921f1befd/billing/wallet/debit" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 1000,
        "reason": "Chargeback correction",
        "idempotencyKey": "debit-2026-04-17-xyz"
      }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "workspaceId": "19c3b12f-ec54-43ad-8686-00e921f1befd",
    "transactionId": "d5f6a7b8-2345-6789-abcd-ef0123456789",
    "amount": 1000,
    "newBalance": 6500,
    "type": "debit",
    "reason": "Chargeback correction",
    "createdAt": "2026-04-17T10:35:00Z"
  }
  ```
</ResponseExample>

<ResponseExample>
  ```json 402 Insufficient Balance theme={null}
  {
    "type": "https://api.nedzo.ai/errors/payment-required",
    "title": "Payment Required",
    "status": 402,
    "detail": "Insufficient wallet balance"
  }
  ```
</ResponseExample>