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

# Update Wallet Status

> This endpoint allows you to update the operational status of an existing wallet. Wallet status controls whether the wallet can be used for transactions and helps enforce risk, compliance, and lifecycle management rules.

## Endpoint

```json theme={null}
PATCH /wallets/{id}/status
```

## Description

Use this endpoint to change the status of a wallet to **active**, **frozen**, or **deleted**.\
Status updates are commonly used to temporarily restrict wallet activity, permanently disable a wallet, or re-enable it after review.

## Path Parameters

| Parameter | Type          | Required | Description                     |
| :-------- | :------------ | :------- | :------------------------------ |
| `id`      | string (UUID) | Yes      | Unique identifier of the wallet |

***

## Request Body

```
{
  "status": "frozen",
  "reason": "Suspicious activity detected"
}
```

***

## Request Fields

| Field    | Type   | Required | Description                                                              |
| :------- | :----- | :------- | :----------------------------------------------------------------------- |
| `status` | string | Yes      | New status to apply to the wallet                                        |
| `reason` | string | No       | Explanation for the status change (recommended for audit and compliance) |

***

## Supported Statuses

| Status    | Description                                              |
| :-------- | :------------------------------------------------------- |
| `active`  | Wallet is enabled and can perform transactions           |
| `frozen`  | Wallet is temporarily disabled; transactions are blocked |
| `deleted` | Wallet is permanently disabled and cannot be reactivated |

***

## Response

### Success Response (200 OK)

```
{
  "data": {
    "id": "wallet_id",
    "status": "frozen"
  }
}
```

***

## Response Fields

| Field    | Type   | Description           |
| :------- | :----- | :-------------------- |
| `id`     | string | Wallet identifier     |
| `status` | string | Updated wallet status |

***

## Example cURL Request

```
curl -X PATCH https://api.yourdomain.com/wallets/{id}/status \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "frozen",
    "reason": "Suspicious activity detected"
  }'
```

***

## Common Errors

| Status Code | Reason                    |
| :---------- | :------------------------ |
| `400`       | Invalid status value      |
| `401`       | Unauthorized request      |
| `404`       | Wallet not found          |
| `422`       | Invalid status transition |

***

## Status Transition Rules (Recommended)

* `active` → `frozen` ✅
* `frozen` → `active` ✅
* `active` → `deleted` ✅
* `frozen` → `deleted` ✅
* `deleted` → any status ❌ (not allowed)

***

## Notes & Best Practices

* Always include a `reason` when freezing or deleting a wallet for audit and compliance purposes.
* Freezing a wallet should immediately block:
  * Incoming transfers
  * Outgoing transfers
  * Payment method usage
* Deleting a wallet should be treated as irreversible.
* Log all status changes for traceability and risk monitoring.

***

## Common Use Cases

* **Freeze wallet** due to suspicious or fraudulent activity
* **Reactivate wallet** after compliance review
* **Delete wallet** when a customer account is closed

***

## Next Steps

After updating a wallet’s status, you may want to:

* Notify the user of the status change
* Review transaction history
* Trigger internal compliance or risk workflows