# Settlement And Suspension

> How to read balances, perform internal transfers for settlement, and use suspension and revocation flows.

Source: https://business-api-docs.youhodler.com/docs/workflows/settlement-and-suspension

Review balances, unwind exposure, and close resources deliberately.

This workflow covers the tail of the lifecycle: balance review, liquidity
return, governance cleanup, and resource suspension or closure across clients,
accounts, and actors.

> **Business impact:** Suspension and closure should follow balance review, open-operation review, and pending-approval review. Lifecycle transitions should not be treated as isolated UI actions.

## Operational Sequence

### 1. Inspect balances and recent operation state

Operational review. Start with actual owner balances and recent operation state before changing lifecycle or access. This avoids suspending resources while financial exposure is still unresolved.

If both enterprise and client balances are in scope, read both before deciding which balances should be returned, settled, or left in place.

[API Reference: List master account balances (GET)](/docs/api/reference/balances/master-accounts-balances)

**Request URL — GET**
```http
GET https://business-api.youhodler.com/master-accounts/22222222-2222-4222-8222-222222222222/balances?asset=USDC
```
**Request URL — GET**
```http
GET https://business-api.youhodler.com/withdrawals?account_ref=client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1&page_size=20
```
**200 Balance Rows**

```json
{
  "items": [
    {
      "asset": "USDC",
      "available": "742500.00",
      "pending_in": "0.00",
      "pending_out": "0.00"
    }
  ]
}
```

**200 Recent Operations**

```json
{
  "items": [
    {
      "id": "eeeeeee5-eeee-4eee-8eee-eeeeeeeeeee5",
      "family": "withdrawal",
      "status": "completed",
      "account_ref": "client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1",
      "principal_amount": {
        "amount": "1250.00",
        "currency": "USDC"
      }
    }
  ],
  "next_page_token": null
}
```

### 2. Return or rebalance liquidity

Internal transfers and withdrawals. Return client-scoped balances to the desired operating boundary before closing accounts or removing access. Rebalancing first keeps lifecycle changes from masking stranded funds.

The same family can rebalance liquidity between internal account boundaries or return balances back to the enterprise treasury perimeter.

[API Reference: Create internal transfer (POST)](/docs/api/reference/internal-transfers/internal-transfers-create)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/internal-transfers
```
**Request Body — application/json**
```json
{
  "amount": {
    "amount": "50000.00",
    "currency": "USDC"
  },
  "source_ref": "client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1",
  "target_ref": "master-accounts/22222222-2222-4222-8222-222222222222"
}
```
**202 Transfer Accepted**

```json
{
  "id": "13131313-1313-4131-8131-131313131313",
  "family": "internal_transfer",
  "status": "processing",
  "account_ref": "master-accounts/22222222-2222-4222-8222-222222222222",
  "principal_amount": {
    "amount": "50000.00",
    "currency": "USDC"
  },
  "fee_summary": null,
  "failure_reason": null,
  "approval_ref": null,
  "subject_attribution": {
    "subject_ref": "enterprises/11111111-1111-4111-8111-111111111111"
  },
  "family_params": {
    "source_ref": "client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1",
    "target_ref": "master-accounts/22222222-2222-4222-8222-222222222222"
  },
  "created_at": "2026-04-28T14:03:01.000Z",
  "updated_at": "2026-04-28T14:03:01.000Z"
}
```

**422 Not Admissible**

```json
{
  "code": "not_admissible",
  "message": "The liquidity return cannot proceed until pending constraints are resolved."
}
```

### 3. Resolve approvals and inspect event consumers

Governance cleanup. Before lifecycle shutdown, check for pending approvals and review recent event flow. This prevents closing a resource while governance or downstream consumers still expect activity.

If lifecycle changes need to be auditable, pair approval review with event review so operator actions and system state remain correlated.

[API Reference: List approvals (GET)](/docs/api/reference/approvals/approvals-list)

**Request URL — GET**
```http
GET https://business-api.youhodler.com/approvals?status=pending
```
**Request URL — GET**
```http
GET https://business-api.youhodler.com/events?aggregate_type=client&aggregate_id=88888888-8888-4888-8888-888888888888
```
**200 Approval Page**

```json
{
  "items": [],
  "next_page_token": null
}
```

**200 Event Page**

```json
{
  "items": [
    {
      "id": "14141414-1414-4141-8141-141414141414",
      "resource": "event",
      "event_type": "client.updated",
      "schema_version": 1,
      "occurred_at": "2026-04-28T14:01:04.000Z",
      "published_at": "2026-04-28T14:01:04.040Z",
      "aggregate": {
        "type": "client",
        "id": "88888888-8888-4888-8888-888888888888"
      },
      "partition_key": "clients/88888888-8888-4888-8888-888888888888",
      "trace_id": "15151515-1515-4151-8151-151515151515",
      "subject_attribution": {
        "subject_ref": "enterprises/11111111-1111-4111-8111-111111111111"
      },
      "enterprise_id": "11111111-1111-4111-8111-111111111111",
      "data": {
        "status": "active"
      },
      "metadata": null
    }
  ],
  "next_page_token": null
}
```

### 4. Suspend or close resources

Lifecycle transitions. Suspend or close clients and client accounts only after the financial boundary is under control. Apply the lifecycle sequence intentionally instead of broad revocation first.

Suspension is useful when the resource may return later. Closure is the stronger terminal state and should usually come after a successful wind-down.

[API Reference: Suspend client (POST)](/docs/api/reference/clients/clients-suspend)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/clients/88888888-8888-4888-8888-888888888888/suspend
```
**Request Body — application/json**
```json
{
  "reason": "Downstream operating perimeter is being offboarded after balance exit."
}
```
**Request URL — POST**
```http
POST https://business-api.youhodler.com/client-accounts/aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1/suspend
```
**200 Client Suspended**

```json
{
  "id": "88888888-8888-4888-8888-888888888888",
  "resource": "client",
  "status": "suspended",
  "parent": "enterprises/11111111-1111-4111-8111-111111111111",
  "external_id": "client-acme-retail-eu",
  "display_name": "Acme Retail Europe",
  "default_client_account": "client-accounts/99999999-9999-4999-8999-999999999999",
  "metadata": {
    "segment": "retail",
    "region": "eu"
  },
  "created_at": "2026-04-28T13:12:01.000Z",
  "updated_at": "2026-04-28T14:08:44.000Z",
  "etag": "W/\"client-4\""
}
```

**200 Client Account Suspended**

```json
{
  "id": "aaaaaaa1-aaaa-4aaa-8aaa-aaaaaaaaaaa1",
  "resource": "client_account",
  "status": "suspended",
  "client": "clients/88888888-8888-4888-8888-888888888888",
  "display_name": "USDC Settlement Account",
  "created_at": "2026-04-28T13:14:33.000Z",
  "updated_at": "2026-04-28T14:08:52.000Z",
  "etag": "W/\"client-account-4\""
}
```

### 5. Revoke access surfaces

Final access cleanup. Revoke service accounts and other access paths only after financial state, approvals, and lifecycle posture have been intentionally wound down.

Access revocation is the last perimeter action. If it happens too early, the integration can lose the ability to inspect, reconcile, or finish closure safely.

[API Reference: Revoke service account (POST)](/docs/api/reference/service-accounts/service-accounts-revoke)

**Request URL — POST**
```http
POST https://business-api.youhodler.com/service-accounts/33333333-3333-4333-8333-333333333333/revoke
```
**Request Body — application/json**
```json
{
  "reason": "Tenant offboarding is complete. Revoke non-human execution access."
}
```
**200 Service Account Revoked**

```json
{
  "id": "33333333-3333-4333-8333-333333333333",
  "resource": "service_principal",
  "status": "revoked",
  "parent": "enterprises/11111111-1111-4111-8111-111111111111",
  "capabilities": [
    "users.read",
    "users.write",
    "policies.read",
    "policies.write"
  ],
  "scope": [
    {
      "target": "enterprises/11111111-1111-4111-8111-111111111111",
      "extent": "perimeter"
    }
  ],
  "profile": "backend-integration",
  "external_id": null,
  "created_at": "2026-04-28T12:49:56.000Z",
  "updated_at": "2026-04-28T14:11:03.000Z",
  "etag": "W/\"service-principal-5\""
}
```

**409 Conflict**

```json
{
  "code": "state_conflict",
  "message": "The service account cannot be revoked while dependent lifecycle transitions remain unresolved."
}
```