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

# 구독 및 청구

각 고객 워크스페이스는 판매하는 티어 중 하나를 구독할 수 있습니다. 리셀러 카드로 모든 워크스페이스의 인보이스를 결제합니다. 워크스페이스의 현재 구독은 `has_payment_issue`와 함께 `workspaces.list`의 `subscription` 필드에 표시됩니다.

## 요금제 할당

아직 요금제가 없는 워크스페이스를 구독시킵니다. `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"
```