PATCH

Update a wallet

ENDPOINT/v1/wallets/{wallet_id}

Applies a partial update to a wallet's status, state reason, credit limit, or daily and monthly spend limits. Omitted fields are left unchanged. Set status to PAUSED to decline new authorizations, or CLOSED to end the wallet. comment is stored with the change and is not returned on the wallet.

Authentication & Headers

Header	Type	Requirement	Description
Authorization	string	REQUIRED	API key passed as an HTTP Bearer token: `Bearer rk_live_...`
X-Program-ID	UUID	PROGRAM-SCOPED	Program boundary UUID that scopes the issuing card, wallet, or transfer.
Content-Type	string	REQUIRED	Must be `application/json`.
Idempotency-Key	string	OPTIONAL	Unique UUID to prevent duplicate execution of financial creations or mutations.

Path Parameters

Parameter	Type	Requirement	Description
wallet_id	string	REQUIRED	Unique identifier of the wallet.

Request Body Schema

application/json

statusstring

optional

Lifecycle of a wallet. `ACTIVE` wallets authorize spend up to available credit and spend limits. `PAUSED` wallets decline new authorizations; balances, statements, and cards remain visible. `CLOSED` wallets accept no new spend; remaining balance is still collected.

Enum values:ACTIVEPAUSEDCLOSED

state_reasonstringnull

optional

Why `status` is `PAUSED` or `CLOSED`. Send null to clear when returning a wallet to `ACTIVE`.

credit_limitobject

optional

Maximum credit extended to this wallet. Also updates credit configuration `credit_limit`. `amount` is a non-negative integer of minor units.

Properties of credit_limit

amountanyrequired

currencystringrequired

ISO 4217 alphabetic currency code.

daily_spend_limitobject

optional

Daily spend cap in the program timezone. `amount` is a non-negative integer of minor units; `50000` with `USD` is $500.00.

Properties of daily_spend_limit

amountanyrequired

currencystringrequired

ISO 4217 alphabetic currency code.

monthly_spend_limitobject

optional

Monthly spend cap in the program timezone. `amount` is a non-negative integer of minor units; `250000` with `USD` is $2,500.00.

Properties of monthly_spend_limit

amountanyrequired

currencystringrequired

ISO 4217 alphabetic currency code.

commentstring

optional

Note stored with this change for audit. Not returned on the wallet.

Response Codes & Schemas

200The wallet after the update.

application/json

{
  "id": "4d8f2a10-6c3e-4b91-9e5a-2f7c8d1e0b44",
  "object": "wallet",
  "kind": "CUSTOMER",
  "status": "PAUSED",
  "state_reason": "Paused at cardholder request.",
  "wallet_entity_id": "2e9c4b71-8a5d-4f03-b6e2-1c7d9a0f3e58",
  "program_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "product_id": "3f0c7a12-5d8e-4a91-b6c2-9e1f0a4d7c33",
  "application_id": "6a0d5e28-1f4b-4c79-a3d6-8e2b9c7f0154",
  "financial_account_ids": [
    "9b3e1c70-4d2a-4f86-8c1b-5e7a2d9f0c14"
  ],
  "credit_limit": {
    "amount": 500000,
    "currency": "USD"
  },
  "available_credit": {
    "amount": 375000,
    "currency": "USD"
  },
  "current_balance": {
    "amount": 125000,
    "currency": "USD"
  },
  "delinquency": {
    "state": "CURRENT",
    "days_past_due": 0,
    "amount_past_due": {
      "amount": 0,
      "currency": "USD"
    }
  },
  "statement_summary": {
    "last_statement_date": "2026-08-15",
    "last_statement_balance": {
      "amount": 125000,
      "currency": "USD"
    },
    "next_statement_date": "2026-09-15",
    "payment_due_date": "2026-09-10",
    "minimum_payment_due": {
      "amount": 3500,
      "currency": "USD"
    }
  },
  "created_at": "2026-08-12T10:15:00Z",
  "updated_at": "2026-08-27T16:20:00Z"
}

400Bad Request: malformed JSON, failed schema validation, or conflicting parameters.

application/json

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "invalid order by: foo. Valid options are: [created_at updated_at]",
    "param": "order_by",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "doc_url": "https://docs.rookpayments.com/errors/invalid_request"
  }
}

401Unauthorized: missing, malformed, or unknown API key.

application/json

{
  "error": {
    "type": "authentication_error",
    "code": "authentication_error",
    "message": "A valid API key is required.",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "doc_url": "https://docs.rookpayments.com/errors/authentication_error"
  }
}

403Forbidden: the API key is denied by RBAC, or it cannot access this program. A resource that exists on another program or organization returns `404 not_found`, not `403`.

application/json

{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The API key cannot access this program.",
    "param": "X-Program-ID",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "doc_url": "https://docs.rookpayments.com/errors/permission_denied"
  }
}

404Not Found: unknown id, or the resource is not visible to this API key.

application/json

{
  "error": {
    "type": "not_found_error",
    "code": "not_found",
    "message": "No card found for the given id.",
    "param": "card_id",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "doc_url": "https://docs.rookpayments.com/errors/not_found"
  }
}

409Conflict: incompatible state, or Idempotency-Key reused with a different body.

application/json

{
  "error": {
    "type": "conflict_error",
    "code": "conflict",
    "message": "The card cannot be reissued from its current state.",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "doc_url": "https://docs.rookpayments.com/errors/conflict"
  }
}

422Unprocessable Entity: the document is valid JSON but violates a business rule.

application/json

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_funds",
    "message": "The source financial account does not have enough available balance.",
    "param": "amount",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "doc_url": "https://docs.rookpayments.com/errors/insufficient_funds"
  }
}

429Too Many Requests: the API key exceeded its rate limit.

application/json

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after the number of seconds in Retry-After.",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "doc_url": "https://docs.rookpayments.com/errors/rate_limited"
  }
}

500Internal Server Error: unexpected failure. Retry with the same Idempotency-Key.

application/json

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected error occurred. Retry with the same Idempotency-Key.",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "doc_url": "https://docs.rookpayments.com/errors/internal_error"
  }
}