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

# 订阅和账单

每个客户工作区可订阅一个你销售的套餐层级。推广伙伴信用卡支付每个工作区的账单。工作区当前订阅位于 `workspaces.list` 的 `subscription` 字段中，同时还包含 `has_payment_issue`。

## 分配套餐

为尚未订阅套餐的工作区订阅。`billing_period` 可为 `monthly_period`（默认）或 `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" }'
```

每次分配或更改套餐时，都要发送自行生成的 `idempotency_key`。如果请求超时，使用相同密钥重试不会导致工作区被重复订阅或重复扣款。

当 `has_payment_issue` 为 `true` 时，无法分配或更改套餐。请向客户展示未支付的账单，或通过其 `pay_url` 完成支付后再重试。

## 更改套餐

`subscriptions.change` 的请求体与 `assign` 相同。

* 升级立即生效。
* 降级或变更至同级套餐会在计费周期结束时生效。在此之前，订阅会在 `pending_downgrade_tier` 中显示新套餐层级，并在 `pending_downgrade_at_unix` 中显示生效日期。

若要让工作区保留当前套餐层级，可使用 `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"
```

降级生效后，超出新套餐限制的接待员和电话号码会被停用，超出团队规模限制的成员会被暂停。

## 终止套餐

`subscriptions.unassign` 会在当前计费周期结束时终止订阅。在此之前，`cancel_at_unix` 会显示终止时间；`subscriptions.restore` 可撤销取消操作，让套餐正常续订。

```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"
```

## 账单

信用卡的每笔扣款对应支付一个工作区的账单。`billing.list_invoices` 按从新到旧的顺序逐页返回账单。账单的 `status` 可为以下值之一：

| 状态     | 含义                           |
| ------ | ---------------------------- |
| `paid` | 已从信用卡扣款。                     |
| `open` | 仍在重试信用卡扣款。`pay_url` 链接至付款页面。 |
| `void` | 重试次数已用尽，工作区套餐已终止。            |

`billing.get_invoice` 会额外返回账单的 `lines`。`amount_cents` 为负值的条目是按比例计算的抵扣金额，所有条目之和始终等于扣款金额。

```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"
```

## 即将到期的付款

`billing.list_upcoming_payments` 会按时间从近到远预估每个工作区的下次续订。`plan_usd` 是续订时预先收取的套餐费用；若已安排降级，则为降级后套餐层级的价格。`overage_so_far_usd` 是当前计费周期内截至目前超出包含分钟数的用量。该费用会在续订时收取，并会持续增长至续订时。

```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"
```