> This is a page from the ElevenLabs documentation. For an index of the documentation, fetch https://elevenlabs.io/docs/llms.txt.

# Abbonamenti e fatturazione

Ogni workspace del cliente può avere un abbonamento a un livello che vendi. La carta del tuo account rivenditore paga le fatture di tutti i workspace. L'abbonamento attuale di un workspace è nel campo `subscription` di `workspaces.list`, insieme a `has_payment_issue`.

## Assegna un piano

Abbonati a un workspace che non ha ancora un piano. `billing_period` può essere `monthly_period` (il valore predefinito) o `annual_period`.

```python
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.reception.subscriptions.assign(
    "8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7",
    tier_id="smbtier_4401k8r2c6hxe9tq3vz7m5wd1nb0",
    billing_period="annual_period",
    idempotency_key="assign-8f1c2a7e-2026-11-03",
)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.reception.subscriptions.assign("8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7", {
  tierId: "smbtier_4401k8r2c6hxe9tq3vz7m5wd1nb0",
  billingPeriod: "annual_period",
  idempotencyKey: "assign-8f1c2a7e-2026-11-03",
});
```

```bash
curl -X POST "https://api.elevenlabs.io/v1/reception/reseller/workspaces/8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7/subscription" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tier_id": "smbtier_4401k8r2c6hxe9tq3vz7m5wd1nb0", "billing_period": "annual_period", "idempotency_key": "assign-8f1c2a7e-2026-11-03" }'
```

Invia un `idempotency_key` generato da te per ogni assegnazione o modifica. Se una richiesta va in timeout, riprovarla con la stessa chiave non può abbonare o addebitare il workspace due volte.

L'assegnazione o la modifica di un piano viene rifiutata se `has_payment_issue` è `true`. Mostra la fattura non pagata al cliente oppure pagala tramite il relativo `pay_url` prima di riprovare.

## Modifica un piano

`subscriptions.change` accetta lo stesso body di `assign`.

* Un upgrade viene applicato immediatamente.
* Un downgrade o il passaggio a un livello dello stesso livello entra in vigore alla fine del periodo di fatturazione. Fino ad allora, l'abbonamento mostra il nuovo livello in `pending_downgrade_tier` e la data in `pending_downgrade_at_unix`.

Per mantenere il workspace sul livello attuale, annulla il downgrade programmato con `subscriptions.cancel_pending_downgrade`.

```python
elevenlabs.reception.subscriptions.change(
    "8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7",
    tier_id="smbtier_4401k8r2d3pfw8ys6bq2n9ja7kc5",
)

elevenlabs.reception.subscriptions.cancel_pending_downgrade("8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7")
```

```typescript
await elevenlabs.reception.subscriptions.change("8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7", {
  tierId: "smbtier_4401k8r2d3pfw8ys6bq2n9ja7kc5",
});

await elevenlabs.reception.subscriptions.cancelPendingDowngrade("8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7");
```

```bash
curl -X PATCH "https://api.elevenlabs.io/v1/reception/reseller/workspaces/8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7/subscription" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tier_id": "smbtier_4401k8r2d3pfw8ys6bq2n9ja7kc5" }'

curl -X POST "https://api.elevenlabs.io/v1/reception/reseller/workspaces/8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7/subscription/cancel-downgrade" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"
```

Quando un downgrade entra in vigore, le receptionist e i numeri di telefono oltre i limiti del nuovo piano vengono disattivati, mentre i membri del team oltre la dimensione prevista vengono sospesi.

## Termina un piano

`subscriptions.unassign` termina l'abbonamento alla fine del periodo di fatturazione corrente. Fino ad allora, `cancel_at_unix` indica quando termina, mentre `subscriptions.restore` annulla la cancellazione affinché il piano si rinnovi normalmente.

```python
elevenlabs.reception.subscriptions.unassign("8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7")

elevenlabs.reception.subscriptions.restore("8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7")
```

```typescript
await elevenlabs.reception.subscriptions.unassign("8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7");

await elevenlabs.reception.subscriptions.restore("8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7");
```

```bash
curl -X DELETE "https://api.elevenlabs.io/v1/reception/reseller/workspaces/8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7/subscription" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"

curl -X POST "https://api.elevenlabs.io/v1/reception/reseller/workspaces/8f1c2a7e4b9d4e6fa3c5b2d1e0f9a8b7/subscription/restore" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"
```

## Fatture

Ogni addebito sulla tua carta paga la fattura di un workspace. `billing.list_invoices` le restituisce dalla più recente, una pagina alla volta. Lo `status` di una fattura può essere:

| Stato  | Significato                                                                              |
| ------ | ---------------------------------------------------------------------------------------- |
| `paid` | La carta è stata addebitata.                                                             |
| `open` | Sono ancora in corso tentativi sulla carta. `pay_url` rimanda a una pagina di pagamento. |
| `void` | I tentativi sono terminati e il piano del workspace è stato concluso.                    |

`billing.get_invoice` aggiunge le `lines` della fattura. Una riga con `amount_cents` negativo è un credito di ripartizione proporzionale e la somma delle righe corrisponde sempre all'addebito.

```python
page = elevenlabs.reception.billing.list_invoices(page_size=25)
for invoice in page.invoices:
    print(invoice.workspace_name, invoice.status, invoice.amount_cents / 100, invoice.currency)

detail = elevenlabs.reception.billing.get_invoice(page.invoices[0].invoice_id)
for line in detail.lines:
    print(line.kind, line.description, line.amount_cents)
```

```typescript
const page = await elevenlabs.reception.billing.listInvoices({ pageSize: 25 });
for (const invoice of page.invoices) {
  console.log(invoice.workspaceName, invoice.status, invoice.amountCents / 100, invoice.currency);
}

const detail = await elevenlabs.reception.billing.getInvoice(page.invoices[0].invoiceId);
for (const line of detail.lines) {
  console.log(line.kind, line.description, line.amountCents);
}
```

```bash
curl "https://api.elevenlabs.io/v1/reception/reseller/billing/invoices?page_size=25" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"
```

## Pagamenti imminenti

`billing.list_upcoming_payments` stima il prossimo rinnovo di ogni workspace, a partire da quello più vicino. `plan_usd` è il piano addebitato in anticipo al rinnovo, ovvero il prezzo del livello con downgrade quando è programmato un downgrade. `overage_so_far_usd` è l'utilizzo di questo periodo che finora supera i minuti inclusi. Viene addebitato al rinnovo e continua a crescere fino ad allora.

```python
upcoming = elevenlabs.reception.billing.list_upcoming_payments()
for payment in upcoming.payments:
    print(
        payment.workspace_name,
        payment.subscription.billing_period_end_unix,
        payment.plan_usd + payment.overage_so_far_usd,
    )
```

```typescript
const upcoming = await elevenlabs.reception.billing.listUpcomingPayments();
for (const payment of upcoming.payments) {
  console.log(
    payment.workspaceName,
    payment.subscription.billingPeriodEndUnix,
    payment.planUsd + payment.overageSoFarUsd
  );
}
```

```bash
curl "https://api.elevenlabs.io/v1/reception/reseller/billing/upcoming" \
  -H "xi-api-key: $ELEVENLABS_API_KEY"
```