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

# Instances and billing

> Create, list, update instances and billing flows with the SDK

Use these resources for account authentication, instance lifecycle, and billing.

For WhatsApp session flows, see [Session](/en/sdk/python/session). For chats, see [Chats](/en/sdk/python/chats). For message sending, see [Messages](/en/sdk/python/messages).

Common fields on instance calls:

| Field            | Type     | Required | Description     |
| ---------------- | -------- | -------- | --------------- |
| `instance_id`    | `string` | Yes      | Instance ID.    |
| `instance_token` | `string` | Yes      | Instance token. |

## Auth

### `client.auth.get_access_token()`

Gets a JWT with `client_token` and `client_secret`. In most flows, resources do this automatically.

```python theme={null}
token = client.auth.get_access_token()
print(token[:16])
```

**Return:** `string` JWT access token (`accessToken` from `POST /token`).

## Instances and billing

### `client.instances.create(...)`

```python theme={null}
created = client.instances.create(
    name="Support",
    webhook="https://example.com/webhooks/vzaps",
    events_subscribe=["Message", "Connected", "Disconnected"],
)
```

**Return:** `InstancePublicCreateResponse` — `id`, `name`, `token`, `url`, `webhook`, `events_subscribe`, `status`, `created_at`, `updated_at`.

### `client.instances.list(...)`

```python theme={null}
instances = client.instances.list(
    page=1,
    size=20,
    search="support",
)
```

**Return:** page `{ page, size, total, total_pages, content[], summary }`. Each `content` item uses the public instance summary shape.

### `client.instances.get(instance_id)`

Returns one instance in the same public summary format as each row from `client.instances.list()`.

```python theme={null}
instance = client.instances.get("VZ...")
```

**Return:** same summary shape as one `instances.list()` item (`id`, `name`, `token`, `url`, `webhook`, `status`, etc.).

### `client.instances.update(instance_id, ..., instance_token=...)`

```python theme={null}
client.instances.update(
    "VZ...",
    name="Commercial Support",
    instance_token="instance-token",
)
```

**Return:** updated instance in the same summary shape as `instances.get()`.

### `client.instances.restart(instance_id, instance_token=...)`

```python theme={null}
client.instances.restart("VZ...", instance_token="instance-token")
```

**Return:** `InstanceActionResponse` — `instance_id`, `status`, `details`.

### `client.instances.delete(instance_id, instance_token=...)`

```python theme={null}
client.instances.delete("VZ...", instance_token="instance-token")
```

**Return:** empty body on success (`204`) or the standard error envelope.

### `client.instances.subscribe(instance_id, ..., instance_token=...)`

```python theme={null}
checkout = client.instances.subscribe(
    "VZ...",
    {},
    instance_token="instance-token",
)
```

**Return:** `BillingHostedSession` — `url`, `session_id`, `mode` (`direct` or checkout), `subscription_id`.

### `client.instances.resume_subscription(instance_id, instance_token=...)`

```python theme={null}
client.instances.resume_subscription("VZ...", instance_token="instance-token")
```

**Return:** `{ status: "ok" }`.

### `client.instances.cancel(instance_id, instance_token=...)`

```python theme={null}
client.instances.cancel("VZ...", instance_token="instance-token")
```

**Return:** `{ message }` confirming cancellation or scheduled cancel.

## Advanced calls

Use `client.request()` when you need an operation not yet wrapped by a resource:

```python theme={null}
client.request(method, path, body=..., query=..., instance_token=...)
```

For the full HTTP contract, use the [API](/en/api-reference/introduction) tab.