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

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# 인보이스

> API를 통해 번호가 매겨진 인보이스로 고객에게 청구하고, 저장된 결제 수단이나 호스팅 체크아웃으로 대금을 받으세요.

인보이스는 한 명의 고객에게 발행하는, 하나 이상의 변형에 대한 번호가 매겨진 청구서입니다. 변형은 판매하는 가격 및 청구 설정으로, 보통 상품에 속합니다. 변형의 ID는 `plan_`으로 시작하며, 인보이스 항목은 이를 `plan_id`로 받습니다. 견적, 서비스, 기업 주문처럼 고객이 결제하기 전에 가격을 합의하는 경우 인보이스를 사용하세요. 초안이 올바르게 될 때까지 작성한 다음, 발행하여 총액을 확정하고 결제를 받을 수 있도록 엽니다. 전송하면 이 작업과 이메일 발송을 한 번의 호출로 수행합니다. 코드 없이 대시보드에서 인보이스를 보내려면 [인보이스 생성 및 전송](https://docs.whop.com/ko/manage-your-business/manage-payments/send-invoice.md)을 참고하세요.

> [!NOTE]
>
> 이 페이지의 인보이스는 모든 요청에 `Api-Version-Date: 2026-10-24` 이상이 필요합니다. 그 이전 버전으로 보낸 요청은 다르게 동작하는 레거시 인보이스 API로 전달됩니다. [시작하기 전에](#before-you-start)를 참고하세요.

## 인보이스의 작동 방식

네이티브 인보이스는 결제입니다. 인보이스의 ID는 `pay_`로 시작하며 고객이 결제한 후에도 동일하게 유지되므로, [결제 조회](https://docs.whop.com/ko/api-reference/payments/retrieve-payment.md)로도 읽을 수 있습니다. 각 인보이스는 계정 고유의 순번에서 다음 번호를 받습니다. 예를 들어 `#00000042`이며, 계정에 인보이스 접두사가 있으면 `#ACME-00000042`가 됩니다.

1. **초안을 만듭니다.** 항목, 고객, 청구 세부 정보를 포함합니다. 초안은 아무것도 청구하지 않으며 누구에게도 이메일을 보내지 않습니다.
2. **발행하거나 전송합니다.** 발행하면 최종 세금이 계산되고 인보이스가 결제를 받을 수 있도록 열립니다. 전송하면 인보이스를 발행하고 즉시 또는 예약한 시간에 이메일로 보냅니다.
3. **고객이 결제합니다.** 인보이스를 발행하거나 전송하면 Whop이 고객의 저장된 결제 수단에 청구하거나, 고객이 Whop의 호스팅 체크아웃을 통해 결제합니다.
4. **`payment.succeeded` 웹훅에서 주문을 처리합니다.**

인보이스는 대기자 명단이 아닌 `release_method: buy_now`인 즉시 구매 변형을 청구합니다. 일회성 변형은 한 번 청구되며, 반복 변형은 인보이스가 결제되면 구독을 시작합니다. 정해진 결제 횟수 후 구독을 중지하는 방법도 다루는 [구독 인보이스 발행](#invoice-a-subscription)을 참고하세요.

## 시작하기 전에

### API 버전 보내기

`/invoices`는 서로 다른 두 API를 제공하며, 요청이 확인되는 `Api-Version-Date`에 따라 어느 쪽이 응답할지 결정됩니다.

| 보내는 값 | `/invoices`가 제공하는 것 |
| - | - |
| `Api-Version-Date: 2026-10-24` 이상 | 이 페이지의 네이티브 인보이스 |
| 이전 `Api-Version-Date` | [레거시 인보이스 API](https://docs.whop.com/ko/api-reference/legacy/invoices/legacy-invoice.md) |
| 헤더 없음 | 자격 증명에 저장된 버전 고정값. 고정값이 없으면 레거시 인보이스 API. |
| 출시된 버전이 아닌 날짜 | `400` 오류 |

발행, 전송, 예약 전송 취소, PDF 생성은 네이티브 API에만 있으므로, 어떤 버전을 보내든 네이티브 인보이스로 전달됩니다. `GET /invoices`와 `POST /invoices/{id}/void`처럼 두 API에 모두 있는 경로는 버전을 따릅니다.

키의 고정값에 의존하지 말고 모든 요청에 헤더를 보내세요. 그래야 키를 바꿔도 두 API 사이를 오가지 않습니다. 고정값과 변경 로그는 [API 버전](https://docs.whop.com/ko/developer/api/versioning.md)에서 설명합니다.

| | 네이티브 인보이스 | 레거시 인보이스 |
| - | - | - |
| **ID** | `pay_`, 결제와 동일 | `inv_` |
| **청구 대상** | `items`로 지정하는 일회성 및 반복 변형 | 일회성 또는 반복 청구 |
| **인보이스 이메일** | Send Invoice를 호출할 때 전송되며, `due_at` 이후 알림 발송 | Whop이 인보이스를 이메일로 보내고 알림 발송 |
| **웹훅** | `payment.*` | `invoice.*` |
| **대시보드** | **Invoices** 탭: 목록 조회, 생성, 전송 | **Legacy invoices** 탭 |

네이티브 API는 레거시 `inv_` 인보이스를 나열하거나 조회하지 않으며, 레거시 API는 네이티브 인보이스를 반환하지 않습니다.

### API 호출하기

이 페이지의 예제는 모든 요청에 버전 헤더를 보내는 작은 헬퍼를 통해 API를 호출합니다.

```typescript TypeScript theme={null}
const WHOP_API = "https://api.whop.com/api/v1";

export async function whop(method: string, path: string, body?: unknown, idempotencyKey?: string) {
	const response = await fetch(`${WHOP_API}${path}`, {
		method,
		headers: {
			Authorization: `Bearer ${process.env.WHOP_API_KEY}`,
			"Api-Version-Date": "2026-10-24",
			"Content-Type": "application/json",
			...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
		},
		body: body === undefined ? undefined : JSON.stringify(body),
	});
	const data = await response.json();
	if (!response.ok) throw new Error(`${data.error.type}: ${data.error.message}`);
	return data;
}
```

```python Python theme={null}
import os
import uuid

import requests

WHOP_API = "https://api.whop.com/api/v1"


def whop(method, path, body=None, idempotency_key=None):
    headers = {
        "Authorization": f"Bearer {os.environ['WHOP_API_KEY']}",
        "Api-Version-Date": "2026-10-24",
    }
    if idempotency_key:
        headers["Idempotency-Key"] = idempotency_key
    response = requests.request(method, f"{WHOP_API}{path}", json=body, headers=headers)
    data = response.json()
    if not response.ok:
        raise RuntimeError(f"{data['error']['type']}: {data['error']['message']}")
    return data
```

재시도로 인해 두 번째 인보이스가 생성되거나 작업이 반복되지 않도록 모든 `POST`에 [`Idempotency-Key`](https://docs.whop.com/ko/developer/api/idempotency)를 보내세요. Generate Invoice PDF는 예외입니다. 호출할 때마다 새 파일을 만들므로 응답을 재생하지 않습니다.

## 초안 만들기

[Create Invoice](https://docs.whop.com/ko/api-reference/invoices/create-invoice.md)는 `POST /invoices`로 초안을 저장합니다.

```typescript TypeScript theme={null}
const invoice = await whop(
	"POST",
	"/invoices",
	{
		account_id: "biz_xxxxxxxxxxxxx",
		email_address: "dana@example.com",
		customer_name: "Dana Lee",
		items: [{ plan_id: "plan_xxxxxxxxxxxxx", quantity: 2 }],
		due_at: "2026-11-30T17:00:00Z",
		billing_address: {
			line1: "123 Main St",
			city: "New York",
			state: "NY",
			postal_code: "10001",
			country: "US",
		},
		metadata: { order_id: "ord_1042" },
	},
	crypto.randomUUID(),
);

console.log(invoice.id, invoice.number, invoice.status); // pay_xxxxxxxxxxxxx #00000042 draft
```

```python Python theme={null}
invoice = whop(
    "POST",
    "/invoices",
    {
        "account_id": "biz_xxxxxxxxxxxxx",
        "email_address": "dana@example.com",
        "customer_name": "Dana Lee",
        "items": [{"plan_id": "plan_xxxxxxxxxxxxx", "quantity": 2}],
        "due_at": "2026-11-30T17:00:00Z",
        "billing_address": {
            "line1": "123 Main St",
            "city": "New York",
            "state": "NY",
            "postal_code": "10001",
            "country": "US",
        },
        "metadata": {"order_id": "ord_1042"},
    },
    idempotency_key=str(uuid.uuid4()),
)

print(invoice["id"], invoice["number"], invoice["status"])  # pay_xxxxxxxxxxxxx #00000042 draft
```

```bash cURL theme={null}
curl -X POST https://api.whop.com/api/v1/invoices \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-10-24" \
  -H "Idempotency-Key: 6f1c2a0e-3b7d-4d55-9a8e-2c4b1f0d9e21" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "biz_xxxxxxxxxxxxx",
    "email_address": "dana@example.com",
    "customer_name": "Dana Lee",
    "items": [{ "plan_id": "plan_xxxxxxxxxxxxx", "quantity": 2 }],
    "due_at": "2026-11-30T17:00:00Z",
    "billing_address": { "line1": "123 Main St", "city": "New York", "state": "NY", "postal_code": "10001", "country": "US" },
    "metadata": { "order_id": "ord_1042" }
  }'
```

응답은 초안과 함께 `201 Created`입니다. 초안을 만들면 아무것도 청구되지 않고, 이메일이나 웹훅도 전송되지 않습니다. 이 응답은 필드의 일부만 보여줍니다:

```json theme={null}
{
	"id": "pay_xxxxxxxxxxxxx",
	"object": "invoice",
	"number": "#00000042",
	"status": "draft",
	"totals_status": "estimated",
	"member_id": "mber_xxxxxxxxxxxxx",
	"recipient_emails": ["dana@example.com"],
	"line_items": [
		{
			"id": "li_xxxxxxxxxxxxx",
			"plan_id": "plan_xxxxxxxxxxxxx",
			"product_id": "prod_xxxxxxxxxxxxx",
			"label": "Strategy workshop",
			"quantity": 2,
			"unit_amount": { "currency": "usd", "amount": "250.00", "decimals": 2, "display_decimals": 2 },
			"subtotal": { "currency": "usd", "amount": "500.00", "decimals": 2, "display_decimals": 2 }
		}
	],
	"subtotal": { "currency": "usd", "amount": "500.00", "decimals": 2, "display_decimals": 2 },
	"tax_amount": null,
	"total": { "currency": "usd", "amount": "500.00", "decimals": 2, "display_decimals": 2 },
	"amount_due": { "currency": "usd", "amount": "500.00", "decimals": 2, "display_decimals": 2 },
	"metadata": { "order_id": "ord_1042" }
}
```

`account_id`는 인보이스를 발행하는 계정으로, 접두사는 `biz_`입니다. 계정 API 키는 이를 생략하면 자신의 계정을 사용합니다. [Create Invoice](https://docs.whop.com/ko/api-reference/invoices/create-invoice.md)에 모든 요청 및 응답 필드가 나와 있습니다.

초안은 생성 시점에 번호를 사용하므로, 폐기한 초안은 순번에 공백을 남깁니다. 초안을 폐기하려면 [삭제하세요](#delete-an-invoice). 목록에 남겨두려면 대신 [무효화하세요](#void-or-mark-uncollectible).

### 항목 추가하기

`items`는 1\~50개의 항목을 받습니다. 각 항목은 기존 변형을 위한 `plan_id` 또는 인라인으로 변형을 찾거나 생성하는 `plan` 중 하나와, 선택적 `quantity`를 받습니다.

인라인 `plan`은 [Create Payment](https://docs.whop.com/ko/api-reference/payments/create-payment.md)와 동일한 찾기 또는 생성 입력을 사용합니다. 예: `{ "plan": { "product_id": "prod_xxxxxxxxxxxxx", "plan_type": "one_time", "initial_price": 250, "currency": "usd" } }`. 이를 위해 `plan:create`가 필요하며, 인라인 `product`에는 상품 권한인 `access_pass:create` 또는 `access_pass:update`도 필요합니다.

생성 및 업데이트는 다음 규칙을 위반하는 항목을 거부합니다:

* 각 항목은 계정의 즉시 구매 변형이어야 합니다. 변형은 한 번만 나타날 수 있으므로, 여러 단위가 필요하면 `quantity`를 사용하세요.
* 보관된 변형이 없어야 하며, 초안을 발행하거나 전송할 때 이를 다시 확인하므로 변형을 보관 해제하거나 다른 변형을 선택하세요.
* `quantity`는 1에서 999,999 사이이며, 여러 수량을 허용하는 변형에서만 1보다 클 수 있습니다. 반복 변형은 이를 허용하지 않으므로 반복 항목의 수량은 1입니다.
* 반복 변형은 상품에 속해야 합니다.
* 모든 항목은 동일한 통화를 사용합니다.
* 여러 항목이 있는 인보이스에서 상품이 있는 모든 항목은 앱이 아닌 일반 상품(표준 상품 유형)이어야 합니다. 반복 항목은 하나의 청구 주기, 무료 체험 기간, `split_pay_required_payments`를 공유하며, 모든 항목은 호환되는 결제, 세금, 액세스 설정이 필요합니다. 사용자 지정 필드나 비밀번호가 있는 변형은 결합할 수 없습니다. 사용자 지정 수수료처럼 상품이 없는 항목은 나머지 항목과 함께 둘 수 있습니다.

응답의 각 품목에는 `label`이 있으며, 이는 상품의 제목이거나 상품이 없는 변형의 경우 변형의 제목입니다. 이메일, PDF, 체크아웃에 이 값이 표시됩니다.

초안은 항목을 저장할 때 각 변형의 가격을 유지하므로, 나중에 변형 가격이 바뀌어도 인보이스는 변하지 않습니다. 일회성 항목은 해당 가격으로 청구됩니다. API 버전 `2026-11-11`부터는 반복 항목을 생성하거나 교체하면 첫 인보이스에 `initial_price`와 `renewal_price`가 함께 포함됩니다. 이전 버전 고정값은 갱신 가격만 사용합니다. `items`를 생략한 편집은 저장된 가격을 유지합니다.

### 고객 및 청구 세부 정보 설정하기

| 필드 | 역할 |
| - | - |
| `member_id` | 고객. 계정의 기존 멤버로, 접두사는 `mber_`입니다. |
| `email_address`, `customer_name` | `member_id` 대신 이메일로 지정하는 고객. Whop은 해당 이메일을 가진 계정의 멤버를 사용하고, 없으면 해당 이메일의 Whop 사용자를 사용하며, 둘 다 없으면 사용자를 만듭니다. `customer_name`은 새 사용자의 이름을 지정합니다. |
| `billing_address` | 고객의 새 청구 주소. `line1`, `city`, `postal_code`, ISO 3166-1 alpha-2 `country`와 선택적 `name`, `line2`, `state`, `phone`을 포함합니다. |
| `mailing_address_id` | 대신 사용할 고객의 저장된 주소 중 하나로, 접두사는 `ma_`입니다. |
| `payment_method_id` | 고객의 저장된 결제 수단으로, 접두사는 `payt_`입니다. 인보이스를 발행하면 Whop이 여기에 청구합니다. [저장된 결제 수단에 청구하기](#charge-a-saved-payment-method)를 참고하세요. |
| `due_at` | 결제 기한(ISO 8601 타임스탬프). `overdue`, 알림 날짜, 이메일·PDF·체크아웃에 표시되는 기한을 설정합니다. |
| `buyer_fee_percentage` | 구매자가 부담하는 수수료로, 소계에 대한 0\~100의 백분율이며 소수점 이하 최대 두 자리입니다. 응답은 백분율을 `buyer_fee_percentage`로, 수수료를 `buyer_fee_amount`로 반환합니다. |
| `recipient_emails` | 청구 대상 고객과 별개로 인보이스 이메일을 받는 최대 50개의 주소. 초안을 만들 때 기본값은 고객의 이메일입니다. 이 필드를 생략한 업데이트는 고객이 바뀌더라도 저장된 목록을 유지합니다. 저장만으로는 이메일이 전송되지 않습니다. [이메일을 받는 사람](#who-gets-the-email)을 참고하세요. |
| `metadata` | 최대 50개의 자체 문자열 키-값 쌍. Whop은 인보이스를 발행할 때 생성하는 멤버십과 자동 청구에 이를 복사합니다. |

`member_id` 또는 `email_address` 중 하나, `billing_address` 또는 `mailing_address_id` 중 하나를 보내세요. 각 쌍을 둘 다 보내서는 안 됩니다. 청구 주소에는 고객이 필요합니다. 초안에서 고객은 선택 사항이지만 발행하려면 필수입니다.

Whop은 인보이스를 발행할 때 청구 주소로 고객의 위치를 파악해 세금을 계산합니다. 세금이 적용되는데 Whop이 고객의 위치를 알 수 없으면 발행이 거부되므로, 세금을 징수할 때는 항상 청구 주소를 추가하세요.

### 초안 편집하기

[Update Invoice](https://docs.whop.com/ko/api-reference/invoices/update-invoice.md)는 `PATCH /invoices/{id}`로 초안을 변경합니다. 변경하는 필드만 보내세요.

```typescript TypeScript theme={null}
const updated = await whop("PATCH", `/invoices/${invoice.id}`, {
	items: [
		{ plan_id: "plan_xxxxxxxxxxxxx", quantity: 3 },
		{ plan_id: "plan_yyyyyyyyyyyyy" },
	],
	buyer_fee_percentage: 2.5,
});
```

```python Python theme={null}
updated = whop(
    "PATCH",
    f"/invoices/{invoice['id']}",
    {
        "items": [
            {"plan_id": "plan_xxxxxxxxxxxxx", "quantity": 3},
            {"plan_id": "plan_yyyyyyyyyyyyy"},
        ],
        "buyer_fee_percentage": 2.5,
    },
)
```

* `items`는 전체 목록을 교체하며 각 변형의 현재 가격을 읽습니다. 저장된 항목과 가격을 유지하려면 생략하세요.
* `member_id`를 변경하면 새 값을 보내지 않는 한 저장된 청구 주소와 결제 수단이 삭제됩니다. `recipient_emails`는 유지되므로 새 목록도 함께 보내세요. 그렇지 않으면 이전 고객이 계속 인보이스 이메일을 받습니다.
* `email_address`와 `customer_name`은 허용되지 않습니다. 다른 사람에게 청구하려면 다른 `member_id`를 보내세요.
* [예약 전송](#schedule-a-send)이 있는 초안은 전송을 취소할 때까지 `recipient_emails` 변경만 허용합니다.
* 인보이스가 발행된 후에는 `recipient_emails`만 단독으로, 그리고 인보이스가 `open` 또는 `uncollectible`인 동안에만 변경할 수 있습니다. 다른 편집은 `400`으로 거부됩니다.

## 고객의 결제 방법 선택하기

발행된 인보이스의 대금을 받는 방법은 두 가지입니다. 저장된 결제 수단은 초안에 들어가므로, 발행하기 전에 하나를 선택하세요.

| | 저장된 결제 수단에 청구 | 고객이 체크아웃으로 결제 |
| - | - | - |
| **고객 참여** | 아니요. Whop이 오프세션으로 결제 수단에 청구합니다. | 예, Whop의 호스팅 체크아웃에서 |
| **필요한 것** | 초안의 `payment_method_id` | 인보이스의 `checkout_link` |
| **3D Secure** | 청구 시 인증 요청을 완료할 수 없음 | 고객이 완료 |
| **결제 규칙** | `block`과 `allow` 적용 | 네 가지 액션 모두 적용 |

발행된 인보이스는 저장된 결제 수단이 있어도 `checkout_link`를 받습니다. 자동 청구가 실패해도 고객은 여전히 체크아웃으로 결제할 수 있습니다.

### 저장된 결제 수단에 청구하기

`payment_method_id`로 초안에 저장된 결제 수단을 넣으세요. 이는 고객의 저장된 결제 수단 중 하나여야 합니다. [결제 수단 저장](https://docs.whop.com/ko/developer/guides/save-payment-methods.md)에서 고객이 결제 수단을 저장하는 방법을 보여주며, [결제 수단 목록](https://docs.whop.com/ko/api-reference/legacy/payment-methods/list-payment-methods.md)으로 멤버가 가진 결제 수단을 찾을 수 있습니다.

인보이스를 발행하거나 전송하고 총액이 0보다 크면 Whop은 다음을 수행합니다:

1. [Create Payment](https://docs.whop.com/ko/api-reference/payments/create-payment.md)가 저장된 결제 수단에 대해 실행하는 것과 동일한 검사를 실행합니다.
2. 인보이스 수량만큼 재고를 예약하고 결제 수수료를 준비합니다.
3. 인보이스를 `open`으로 반환하고 결제 수단에 오프세션으로 청구합니다. 청구는 Issue Invoice 또는 Send Invoice에 전달한 `charge_at`에 실행되고, 그렇지 않으면 아직 도래하지 않은 경우 `due_at`에, 그 외에는 즉시 실행됩니다. `scheduled_charge_at`은 아직 예정된 청구를 보여줍니다.

응답은 청구 성공 여부를 알려주지 않습니다. 인보이스의 `pay_` ID에 대한 [`payment.succeeded` 웹훅](#webhooks)에서 주문을 처리하세요. 결제된 인보이스는 멤버십을 완료하며, `metadata`는 청구와 멤버십에 기록됩니다. 결제 규칙이 청구를 심사하는 방법은 [인보이스 결제에 대한 결제 규칙](#payment-rules-on-invoice-payments)에서 다룹니다.

### 자동 청구가 거절된 경우

청구가 거절되면 인보이스는 `open` 상태로 유지되고 예약된 재고가 반환됩니다. [인보이스를 결제로 조회](https://docs.whop.com/ko/api-reference/payments/retrieve-payment.md)하고 `failure_message`를 읽어 최근 시도가 실패한 이유를 확인하세요.

청구가 거절되거나 고객의 조치가 필요하면, Whop은 고객이 대신 체크아웃으로 결제할 수 있도록 인보이스의 결제 링크를 [수신자](#who-gets-the-email)에게 이메일로 보냅니다. 이는 전송하지 않고 발행한 인보이스에 대해 Whop이 보내는 유일한 이메일입니다. 이를 위해서는 `checkout_link`와 `recipient_emails`에 하나 이상의 항목이 필요하며, [전송 한도](#send-limit)에 포함되지 않습니다.

> [!WARNING]
>
> 오프세션 청구는 고객에게 3D Secure 인증 요청을 표시할 수 없습니다. 은행이 인증을 요구하면 자동 청구가 완료되지 않으며, 고객이 인증하거나 다른 방법으로 결제할 때까지 인보이스는 미결제 상태로 남습니다.

## 인보이스 발행하기

[Issue Invoice](https://docs.whop.com/ko/api-reference/invoices/issue-invoice.md)는 초안을 열린 인보이스로 전환합니다. Whop은 인보이스를 다시 확인하고, 최종 세금을 계산하고, `status`를 `open`으로, `totals_status`를 `final`로 설정합니다. 인보이스에 저장된 결제 수단이 있고 총액이 0보다 크면, Whop은 [저장된 결제 수단에 청구하기](#charge-a-saved-payment-method)에 설명된 대로 청구합니다.

```typescript TypeScript theme={null}
const issued = await whop("POST", `/invoices/${invoice.id}/issue`, undefined, crypto.randomUUID());

console.log(issued.status, issued.totals_status); // open final
```

```python Python theme={null}
issued = whop("POST", f"/invoices/{invoice['id']}/issue", idempotency_key=str(uuid.uuid4()))

print(issued["status"], issued["totals_status"])  # open final
```

```bash cURL theme={null}
curl -X POST https://api.whop.com/api/v1/invoices/pay_xxxxxxxxxxxxx/issue \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-10-24" \
  -H "Idempotency-Key: 0b6f2d3c-91a4-4c7e-8f1e-5a2d7c9b3e10"
```

* **세금이 확정됩니다.** `tax_amount`는 초안에서는 `null`이며 발행하면 설정됩니다. `total`과 `amount_due`에 세금이 포함됩니다.
* **인보이스가 상품을 청구하면 Whop이 고객의 멤버십을 만듭니다.** 멤버십은 인보이스가 결제될 때까지 액세스 없이 초안 상태로 유지됩니다. 모든 항목에 상품이 없는 인보이스는 멤버십을 받지 않습니다.
* **`payment.created`가 인보이스의 `pay_` ID에 대해 한 번 발생합니다.**
* **다시 발행해도 안전합니다.** 이미 `open`인 인보이스를 발행하면 동일한 검사를 다시 실행하고, 통과하면 인보이스를 변경 없이 반환합니다. 총액은 그대로이며 다시 청구되지 않습니다.
* **발행해도 인보이스가 이메일로 전송되지 않습니다.** 단, [청구 거절 후 결제 링크](#if-the-automatic-charge-is-declined)는 예외입니다. 인보이스를 이메일로 보내려면 대신 [전송하거나](#send-schedule-and-remind) 체크아웃 링크를 직접 전달하세요.

거부된 발행은 아무것도 변경하거나 청구하지 않습니다. 원인을 해결하고 인보이스를 다시 발행하세요. 이유는 [발행 오류](#issue-errors)에 나와 있습니다.

### 체크아웃 링크 받기

발행된 `open` 인보이스에는 `pay_xxxxxxxxxxxxx.<signature>` 형식의 서명된 값인 `checkout_link`가 있습니다. 이 링크는 고정 가격으로 Whop의 호스팅 체크아웃에서 인보이스를 엽니다.

**1. 발행된 인보이스에서 링크 읽기**

`checkout_link`는 인보이스가 `open`이 아니면 `null`이므로, 초안과 결제 완료, 무효, 회수 불가 인보이스에는 링크가 없습니다. 비즈니스 구매자에게 청구된 인보이스, 멤버십이 취소된 인보이스, 자격 증명에 `payment:charge`가 없는 경우에도 `null`입니다. 비즈니스 구매자는 개인이 아닌 다른 Whop 계정인 고객입니다.

**2. 호스팅 체크아웃 URL 만들기**

링크를 첫 번째 `.`에서 나누세요. 그 앞은 인보이스의 `pay_` ID이고, 뒤는 토큰입니다.

```typescript TypeScript theme={null}
const { id, checkout_link } = await whop("GET", `/invoices/${invoice.id}`);

if (checkout_link) {
	const token = checkout_link.slice(checkout_link.indexOf(".") + 1);
	const url = `https://whop.com/checkout/${id}/?token=${encodeURIComponent(token)}`;
	console.log(url);
}
```

```python Python theme={null}
from urllib.parse import quote

current = whop("GET", f"/invoices/{invoice['id']}")

if current["checkout_link"]:
    token = current["checkout_link"].split(".", 1)[1]
    url = f"https://whop.com/checkout/{current['id']}/?token={quote(token, safe='')}"
    print(url)
```

**3. 고객에게 보내기**

[인보이스를 전송](#send-schedule-and-remind)하여 Whop이 링크를 이메일로 보내게 하거나, URL을 자체 이메일이나 인보이스 페이지에 넣으세요. 인보이스의 고객만 이 링크로 결제할 수 있습니다. 다른 사람은 거부되며 인보이스의 고객으로 로그인하라는 요청을 받습니다. 인보이스가 결제, 무효화, 회수 불가로 표시되면 링크는 더 이상 작동하지 않습니다.

**4. 웹훅에서 주문 처리하기**

자동 청구와 마찬가지로 인보이스의 `pay_` ID에 대한 `payment.succeeded`를 수신하세요. [웹훅](#webhooks)에서 핸들러 예시를 보여줍니다.

체크아웃은 항목 옆에 인보이스 번호와 기한을 표시하며, 기한이 지나면 기한이 빨간색으로 바뀝니다. 고객은 인보이스의 항목과 총액을 결제하며 프로모션 코드를 추가할 수 없습니다.

## 전송, 예약, 알림

[Send Invoice](https://docs.whop.com/ko/api-reference/invoices/send-invoice.md)는 `POST /invoices/{id}/send`로 인보이스를 이메일로 보냅니다. 초안을 전송하면 Issue Invoice와 동일하게 먼저 발행합니다. `open` 인보이스를 전송하면 다시 이메일로 보냅니다.

```typescript TypeScript theme={null}
await whop("POST", `/invoices/${invoice.id}/send`, undefined, crypto.randomUUID());
```

```python Python theme={null}
whop("POST", f"/invoices/{invoice['id']}/send", idempotency_key=str(uuid.uuid4()))
```

이메일에는 계정의 이름과 로고, 인보이스 번호, 총액, 기한, 각 항목, 인보이스의 체크아웃을 여는 버튼이 표시됩니다. Whop은 고객이 이메일에서 결제할 수 있는 인보이스만 이메일로 보냅니다. `open` 인보이스를 전송하려면 `checkout_link`가 필요하고, 초안에는 비즈니스 구매자가 아닌 고객이 필요합니다. 비즈니스 구매자에게 청구된 초안도 저장된 결제 수단이 있으면 대신 청구되므로 전송할 수 있습니다.

### 이메일을 받는 사람

각 전송은 모든 주소에 개별 이메일로 한 번씩 보내므로, 수신자는 서로의 주소를 볼 수 없습니다. 주소는 다음과 같습니다:

* 고객의 Whop 계정 이메일. 인보이스 PDF의 **Bill to** 아래에 인쇄됩니다.
* `recipient_emails`의 각 항목.

Whop은 `recipient_emails`를 소문자로 저장하고 목록의 중복을 제거하므로, 두 곳에 모두 있는 주소는 이메일을 한 통만 받습니다.

`recipient_emails`가 비어 있으면 Whop은 고객을 포함해 아무에게도 이메일을 보내지 않습니다. Whop이 인보이스를 이메일로 보내지 않게 하려면 이를 사용하세요:

* 저장된 결제 수단에 대신 청구하는 경우가 아니면 Send Invoice가 인보이스를 거부합니다.
* 청구가 거절된 후 [결제 링크](#if-the-automatic-charge-is-declined)가 발송되지 않습니다.
* 알림이 발송되지 않습니다. `open` 인보이스의 `recipient_emails`를 비우면 남은 알림이 중지됩니다.

### Whop이 이메일 대신 청구하는 경우

`payment_method_id`가 있고 총액이 0보다 큰 초안은 발행할 때와 마찬가지로 이메일 대신 청구됩니다. 청구가 실패하면 어떻게 되는지는 [자동 청구가 거절된 경우](#if-the-automatic-charge-is-declined)에서 다룹니다. 이런 초안은 이메일이 필요한 사람이 없으므로 `recipient_emails`가 비어 있어도 전송할 수 있습니다.

### 전송 한도

각 인보이스는 발행 시 전송을 포함해 24시간 내에 세 번까지 이메일로 보낼 수 있습니다. 그 기간 내 네 번째 전송은 `error.code`가 `invoice_send_limit_reached`인 `429`로 거부됩니다. 알림, [청구 거절 후 결제 링크](#if-the-automatic-charge-is-declined), 이메일 대신 청구하는 전송은 한도에 포함되지 않습니다.

### 전송 예약하기

초안을 나중에 보내려면 `send_at`을 전달하세요. 초안은 초안 상태로 유지되며 `scheduled_send_at`에 시간을 표시합니다. 그 시간이 되면 Whop은 그때 Send Invoice를 호출한 것처럼 초안을 전송합니다.

```typescript TypeScript theme={null}
const scheduled = await whop("POST", `/invoices/${invoice.id}/send`, { send_at: "2026-12-01T15:00:00Z" }, crypto.randomUUID());

console.log(scheduled.status, scheduled.scheduled_send_at); // draft 2026-12-01T15:00:00.000Z
```

```python Python theme={null}
scheduled = whop("POST", f"/invoices/{invoice['id']}/send", {"send_at": "2026-12-01T15:00:00Z"}, idempotency_key=str(uuid.uuid4()))

print(scheduled["status"], scheduled["scheduled_send_at"])  # draft 2026-12-01T15:00:00.000Z
```

* **초안만 예약할 수 있으며,** `send_at`은 미래여야 합니다. Whop은 지금 전송할 때와 마찬가지로 예약 시점에 수신자와 결제 링크를 확인합니다.
* **새 `send_at`으로 다시 전송하면** 시간이 변경됩니다.
* **전송이 이루어지거나 취소할 때까지 편집이 잠깁니다.** `recipient_emails`만 변경하는 업데이트는 여전히 작동하지만, 청구되지 않을 초안에서 마지막 수신자를 제거할 수는 없습니다.
* **`POST /invoices/{id}/unschedule`로 [예약 전송을 취소](https://docs.whop.com/ko/api-reference/invoices/cancel-scheduled-send.md)하세요.** `scheduled_send_at`이 `null`로 돌아가고 초안을 다시 편집할 수 있습니다. 예약 전송이 없는 인보이스를 취소하면 변경 없이 반환됩니다.
* **예약된 초안을 무효화하면** 예약 전송이 중지됩니다.

```typescript TypeScript theme={null}
await whop("POST", `/invoices/${invoice.id}/unschedule`, undefined, crypto.randomUUID());
```

```python Python theme={null}
whop("POST", f"/invoices/{invoice['id']}/unschedule", idempotency_key=str(uuid.uuid4()))
```

Whop은 매분 전송 예정 항목을 확인하므로, 예약 전송은 `send_at` 후 약 1분 이내에 발송됩니다. 예를 들어 예약 이후 변형이 삭제되어 전송이 거부되면, 인보이스는 초안으로 유지되고 `scheduled_send_at`은 `null`로 돌아가며, API는 그 이유를 반환하지 않습니다. 그 외의 실패는 약 10분마다, 총 최대 12회까지 재시도됩니다. 시도가 성공하거나 Whop이 재시도를 중단할 때까지 `scheduled_send_at`은 `null`이 아닌 다음 시도 시간을 표시합니다. `send_at` 이후에 인보이스를 읽어 `open`인지 확인하세요.

### 알림

Send Invoice가 `due_at`이 있는 인보이스를 이메일로 보내면, Whop은 `due_at` 후 1, 3, 7, 14, 30, 60일에 알림도 예약하며, 날짜가 이미 지난 알림은 건너뜁니다. 각 알림은 인보이스와 같은 주소로 전송되며 인보이스의 연체 일수를 알려줍니다.

알림은 인보이스가 `open`인 동안에만 발송되므로, 결제, 무효화, 회수 불가로 표시되면 중지됩니다. 결제가 진행 중일 때 기한이 된 알림은 결제가 끝날 때까지 기다립니다. 전송하지 않고 발행한 인보이스나 이메일 대신 청구된 인보이스는 알림을 받지 않습니다.

### 이메일 기록

[List Invoice Sends](https://docs.whop.com/ko/api-reference/invoices/list-invoice-sends.md)는 `GET /invoices/{id}/sends`로 기록된 이메일 배치를 최신순으로 반환합니다. 최초 및 반복 이메일, 예약 이메일, 알림, 저장된 결제 수단에 대한 청구 실패 후 결제 후속 이메일이 포함됩니다. 가장 최근에 기록된 전송은 첫 번째 항목을 사용하고, 이전 항목을 읽으려면 `page_info.end_cursor`를 `after`로 사용하세요. 수동 배치는 인보이스에 이전에 완료된 이메일 기록이 없으면 `send`를, 그렇지 않으면 `resend`를 사용합니다. 종류는 완료된 배치가 기록될 때 선택되므로, 함께 대기열에 들어간 요청은 완료 순서대로 분류됩니다. 이전에 기록되지 않은 이메일은 알 수 없는 상태로 남습니다.

각 항목에는 `kind`, `sent_at`, `recipient_count`, `recipients`, `actor`가 포함됩니다. 기록을 읽으려면 `payment:basic:read`가 필요합니다. 주소에는 `member:email:read`도 필요합니다. 이 권한이 없으면 `recipients`는 비어 있습니다. 발신자에는 `company:authorized_user:read`도 필요합니다. 그렇지 않으면 `actor`는 null입니다. 자동 전송과 계정 API 키도 actor가 null입니다.

워커는 전체 배치를 전달용으로 제출한 후 항목을 추가합니다. 부분 배치의 경우 재시도로 배치가 완료된 경우에만 항목을 추가합니다. 항목은 원래 수신자 목록을 유지합니다. 기록된 배치가 받은편지함 전달을 보장하지는 않습니다. 전달 전에 인보이스나 수신자가 변경되면 메일러가 메시지를 보내지 않을 수 있습니다. 기록에는 이 기능이 도입되기 전에 전송된 이메일이 포함되지 않습니다. 이메일 없이 인보이스를 발행하면 기록 항목이 추가되지 않습니다.

## PDF 다운로드하기

[Generate Invoice PDF](https://docs.whop.com/ko/api-reference/invoices/generate-invoice-pdf.md)는 인보이스를 PDF로 만들고 단기 링크를 반환합니다. `payment:basic:read`가 필요하며 모든 상태에서 작동합니다.

```typescript TypeScript theme={null}
const pdf = await whop("POST", `/invoices/${invoice.id}/generate_pdf`);

console.log(pdf.url, pdf.expires_at);
```

```python Python theme={null}
pdf = whop("POST", f"/invoices/{invoice['id']}/generate_pdf")

print(pdf["url"], pdf["expires_at"])
```

응답에는 `url`과 `expires_at`이 있습니다. 링크는 15분 동안 유효하며, 링크를 가진 누구나 파일을 다운로드할 수 있습니다. 만료되면 새 링크를 생성하세요.

PDF는 비즈니스를 앞세웁니다. 계정 이름이 페이지 상단에 표시되고, 바닥글에는 Whop Inc가 귀하의 이름으로 귀하를 대신하여 인보이스를 발행한다고 명시됩니다. 인보이스 번호, 발행일과 기한, **Bill to** 세부 정보가 표시됩니다. 각 항목에는 수량, 단가, 금액이 표시되고, 그 뒤에 소계, 서비스 수수료, 세금, 청구 금액이 이어집니다. 반복 항목이 있는 인보이스는 갱신 금액과 갱신 주기도 명시합니다. 초안의 PDF는 예상 총액을 표시하며, 발행할 때까지 세금은 0입니다.

일부 콘텐츠는 자격 증명의 권한에 따라 달라집니다:

| 권한 | PDF에 추가되는 내용 |
| - | - |
| `member:basic:read` | **Bill to** 아래의 고객 이름. 이 권한이 없으면 PDF에는 청구 주소에 저장된 이름만 표시됩니다. |
| `member:email:read` | **Bill to** 아래의 고객 이메일 |
| `payment:charge` | `checkout_link`가 있는 인보이스에서 인보이스의 체크아웃을 여는 **Pay now** 링크 |

## 구독 인보이스 발행하기

인보이스에 반복 변형을 넣으면 고객이 결제할 때 구독이 시작됩니다. 이후 Whop은 청구 주기마다 한 번씩 구독을 갱신합니다.

1. **인보이스는 첫 번째 주기와 선불 수수료를 청구합니다.** 반복 항목은 상품에 속해야 하며 수량은 1입니다. API 버전 `2026-11-11`부터 첫 인보이스는 `initial_price`와 `renewal_price`를 함께 청구합니다. 변형에 무료 체험이 없으면 결제와 동시에 첫 번째 유료 청구 주기가 시작됩니다. 무료 체험이 있으면 구독은 [체험으로 시작합니다](#start-with-a-free-trial). 대시보드에서 사용자 지정 반복 항목에는 선택적인 **Upfront fee** 필드가 있습니다. 품목의 `initial_price`는 `unit_amount` 중 일회성 부분을 나타내며, 인보이스 페이지, 이메일, PDF에서 별도의 **Upfront fee** 줄로 표시됩니다.
2. **인보이스를 결제하면 구독이 시작됩니다.** Whop이 발행 시 저장된 결제 수단에 청구하든, 고객이 `checkout_link`로 결제하든 마찬가지입니다. 첫 번째 주기는 결제 시점에 시작됩니다. 링크로 연 체크아웃에는 인보이스의 구매자 수수료를 포함한 갱신 금액과 갱신 주기가 표시됩니다.
3. **각 갱신은 인보이스를 발행하거나 전송할 때 선택한 방식으로 수금됩니다.** 갱신은 인보이스의 구매자 수수료와 함께 반복 항목만, 인보이스 발행 시점의 각 변형 갱신 가격으로 청구합니다. 항목을 저장한 후 변형 가격이 바뀌었다면 이는 초안에 저장된 가격과 다를 수 있습니다. 일회성 항목은 한 번만 청구됩니다.

[Issue Invoice](https://docs.whop.com/ko/api-reference/invoices/issue-invoice.md) 또는 [Send Invoice](https://docs.whop.com/ko/api-reference/invoices/send-invoice.md)에 `collection_method`를 전달하여 갱신 수금 방식을 선택하세요. 예약 전송은 예약할 때 지정한 `collection_method`를 적용하며, 초안에는 이것이 `scheduled_collection_method`로 표시됩니다.

| `collection_method` | 각 갱신 |
| - | - |
| `charge_automatically` | 인보이스를 결제한 결제 수단에 청구합니다. 초안의 `payment_method_id` 또는 고객이 인보이스 링크로 결제한 결제 수단입니다. 기본값입니다. |
| `send_invoice` | 갱신일이 기한인 새 번호의 인보이스를 발행하고, 결제 링크 및 알림과 함께 최신 인보이스의 `recipient_emails`로 이메일을 보냅니다 |

`send_invoice`에는 최소 하나의 `recipient_emails` 주소가 필요하며, 비즈니스에 청구된 인보이스에는 사용할 수 없습니다. 이 방식이 적용되는 동안에는 인보이스의 마지막 수신자를 제거할 수 없습니다. 반복 항목이 없는 인보이스는 `collection_method`를 거부합니다. 첫 인보이스를 카드로 결제해도 `send_invoice`는 유지됩니다.

각 갱신은 고유한 `pay_` ID와 `payment.*` 웹훅을 가진 별도의 결제입니다. `charge_automatically` 갱신은 번호가 매겨진 인보이스가 아니므로 List Invoices에 나타나지 않습니다. `send_invoice` 갱신은 List Invoices에 나타나는 번호가 매겨진 인보이스이며, Whop은 이를 자동으로 청구하지 않습니다. 고객이 인보이스의 `checkout_link`로 결제할 때까지 구독은 `past_due` 상태로 유지됩니다. 그동안 고객은 액세스를 유지합니다. 갱신을 중지하려면 [멤버십을 취소](https://docs.whop.com/ko/api-reference/memberships/cancel-membership.md)하세요. 멤버십이 취소되면 열린 갱신 인보이스의 `checkout_link`는 더 이상 작동하지 않습니다.

구독을 찾으려면 [인보이스를 결제로 조회](https://docs.whop.com/ko/api-reference/payments/retrieve-payment.md)하고 `membership_id`를 읽으세요. 이를 위해 `member:basic:read`가 필요합니다.

### 무료 체험으로 시작하기

인보이스는 체크아웃과 마찬가지로 반복 변형의 `trial_period_days`를 따릅니다. 첫 인보이스는 변형의 `initial_price`만 청구합니다. 이를 결제하면 체험이 시작되고, 체험이 끝나면 첫 번째 갱신이 `renewal_price`를 청구합니다. 2026-11-16 17:00 UTC 이전에 생성된 인보이스는 첫 번째 주기를 청구하고 체험을 건너뜁니다.

* 이미 해당 변형을 구독한 적이 있는 고객은 체험을 받지 않습니다. 첫 인보이스는 `initial_price`와 `renewal_price`를 함께 청구합니다. 갱신 인보이스는 절대 체험을 시작하지 않습니다.
* 체험은 변형에서 결정됩니다. 사용자 지정 반복 항목의 경우 `variant.trial_period_days`를 설정하세요. 항목 수준의 `trial_period_days`는 거부됩니다.
* 인보이스의 모든 반복 항목은 체험 기간이 같아야 합니다.
* 인보이스가 아무것도 청구하지 않을 때는 체험을 즉시 시작하는 `payment_method_id`와 함께, 또는 `collection_method: "send_invoice"`와 함께 발행하거나 전송하세요.
* 대시보드에서 사용자 지정 반복 항목에는 **Free trial days** 필드가 있습니다. 상품의 청구 플랜은 자체 체험을 표시합니다.

### 정해진 결제 횟수 후 중지하기

6회 월별 결제와 같은 고정 결제 플랜을 청구하려면 반복 변형에 `split_pay_required_payments`를 2\~115 사이로 설정하세요. 인보이스는 선불 수수료를 포함한 첫 번째 결제입니다. 예를 들어 $75 선불 수수료와 $40씩 3회 할부는 $115, $40, \$40을 청구합니다. Whop은 해당 횟수의 결제가 이루어지면 갱신을 중지하며 멤버십은 활성 상태로 유지됩니다. 그 전에는 고객이 직접 구독을 취소할 수 없지만 판매자는 취소할 수 있습니다. 구독이 취소될 때까지 갱신하려면 설정하지 마세요.

## 상태와 수명 주기

| `status` | 의미 | 다음에 일어날 수 있는 일 |
| - | - | - |
| `draft` | 아직 편집할 수 있습니다. 총액은 추정치이며 세금은 아직 계산되지 않았습니다. | 발행, 전송, 예약, 무효화 또는 삭제 |
| `open` | 발행됨. 총액과 세금이 확정되었으며 인보이스가 결제를 기다리고 있습니다. | 고객이 결제하거나, 무효화하거나 회수 불가로 표시 |
| `paid` | 고객이 결제했습니다. `amount_due`는 0입니다. | 없음 |
| `uncollectible` | 수금을 기대하지 않는 열린 인보이스로 표시했습니다. | 무효화 |
| `void` | 취소됨. `amount_due`는 0입니다. | 삭제 |

`status`는 결제에서 값을 가져오므로, 결제가 진행 중일 때 인보이스에 `pending` 같은 결제 상태가 표시될 수도 있습니다. `totals_status`는 금액 필드가 확정되었는지 알려줍니다. 인보이스가 초안인 동안은 `estimated`, 발행 후에는 `final`입니다. `overdue`는 `due_at`이 지난 `open` 또는 `uncollectible` 인보이스에서 `true`입니다.

### 무효화 또는 회수 불가로 표시하기

[Void Invoice](https://docs.whop.com/ko/api-reference/invoices/void-invoice.md)는 `draft`, `open`, `uncollectible` 인보이스를 취소합니다. 이미 무효인 인보이스를 무효화하면 변경 없이 반환되며, 결제된 인보이스는 무효화할 수 없습니다.

수금을 기대하지 않는다는 것을 기록하려면 [인보이스를 회수 불가로 표시](https://docs.whop.com/ko/api-reference/invoices/mark-invoice-uncollectible.md)하세요. `open` 인보이스만 표시할 수 있으며, 회수 불가 인보이스를 다시 표시하면 변경 없이 반환됩니다. 회수 불가 인보이스에는 `checkout_link`가 없으며 알림을 받지 않습니다.

이 예제는 `open` 인보이스를 회수 불가로 표시한 다음 무효화합니다:

```typescript TypeScript theme={null}
await whop("POST", `/invoices/${invoice.id}/mark_uncollectible`, undefined, crypto.randomUUID());

await whop("POST", `/invoices/${invoice.id}/void`, undefined, crypto.randomUUID());
```

```python Python theme={null}
whop("POST", f"/invoices/{invoice['id']}/mark_uncollectible", idempotency_key=str(uuid.uuid4()))

whop("POST", f"/invoices/{invoice['id']}/void", idempotency_key=str(uuid.uuid4()))
```

### 인보이스 삭제하기

[Delete Invoice](https://docs.whop.com/ko/api-reference/invoices/delete-invoice.md)는 `DELETE /invoices/{id}`로 `draft` 또는 `void` 인보이스를 제거합니다. 응답은 `{ id, deleted: true }`입니다. 삭제된 인보이스는 더 이상 List Invoices나 List Payments에 나타나지 않으며, 해당 ID는 `404`를 반환합니다. 삭제는 취소할 수 없습니다.

`open` 인보이스는 삭제하기 전에 무효화하세요. 예약 전송이나 청구가 있는 초안은 먼저 [Cancel Scheduled Send](https://docs.whop.com/ko/api-reference/invoices/cancel-scheduled-send.md)가 필요합니다. 초안 갱신 인보이스는 구독을 청구하는 동안 삭제할 수 없습니다. 돈을 수금했거나 아직 은행 송금을 기다리는 무효 인보이스는 삭제할 수 없으며, 결제 완료, 보류 중, 회수 불가 인보이스도 마찬가지입니다. 인보이스를 삭제할 수 있으면 `deletable` 필드가 `true`입니다.

삭제하려면 `invoice:update` 또는 `payment:charge`가 필요합니다. 삭제된 초안의 번호는 재사용되지 않습니다.

```typescript TypeScript theme={null}
await whop("DELETE", `/invoices/${invoice.id}`);
```

```python Python theme={null}
whop("DELETE", f"/invoices/{invoice['id']}")
```

## 인보이스 목록 조회 및 조회

[List Invoices](https://docs.whop.com/ko/api-reference/invoices/list-invoices.md)는 자격 증명으로 읽을 수 있는 인보이스를 최신순으로 반환합니다. API 키는 자신의 계정을 보고, 사용자 토큰은 사용자가 결제를 읽을 수 있는 모든 계정을 봅니다. 다음 쿼리 매개변수로 목록을 좁히세요:

| 매개변수 | 필터 대상 |
| - | - |
| `account_id` | 하나의 계정 |
| `status` | `open` 같은 하나의 상태. 알 수 없는 값은 `400`입니다. |
| `overdue` | 연체된 인보이스는 `true`, 나머지는 `false` |
| `scheduled` | 예약된 초안은 `true`, 나머지는 `false` |
| `member_id` | 한 명의 고객 |
| `product_id` | 상품을 청구하는 인보이스. 접두사는 `prod_` |
| `created_after`, `created_before` | ISO 8601 타임스탬프로 지정하는 생성 기간 |

예약된 초안은 `scheduled_send_at`이 있는 초안입니다. `open` 인보이스는 절대 예약 상태가 아니며, 기한에 전송되는 초안도 마찬가지입니다.

`order`(`created_at`, `due_at`, `scheduled_send_at`)와 `direction`(`asc` 또는 `desc`)으로 정렬하세요. `due_at` 또는 `scheduled_send_at`으로 정렬하면 해당 날짜가 없는 인보이스가 마지막에 옵니다. 응답은 `{ data, page_info }`입니다. `page_info.has_next_page`가 `true`인 동안 `page_info.end_cursor`를 `after`로 전달하여 다음 페이지를 읽으세요.

```typescript TypeScript theme={null}
const overdue = await whop("GET", "/invoices?account_id=biz_xxxxxxxxxxxxx&overdue=true&order=due_at&direction=asc");

for (const invoice of overdue.data) {
	console.log(invoice.number, invoice.due_at, invoice.amount_due.amount);
}
```

```python Python theme={null}
overdue = whop("GET", "/invoices?account_id=biz_xxxxxxxxxxxxx&overdue=true&order=due_at&direction=asc")

for invoice in overdue["data"]:
    print(invoice["number"], invoice["due_at"], invoice["amount_due"]["amount"])
```

[Retrieve Invoice](https://docs.whop.com/ko/api-reference/invoices/retrieve-invoice.md)는 `pay_` ID로 인보이스 하나를 읽습니다. [List Payments](https://docs.whop.com/ko/api-reference/payments/list-payments.md)는 초안을 제외합니다.

인보이스를 CSV 파일로 내보내려면 `resource: "receipt_invoices"`로 [Create Export](https://docs.whop.com/ko/api-reference/exports/create-export.md)를 호출하세요. `payment:basic:read`와 `payment:basic:export`가 필요합니다. 고객 열은 자격 증명에 `member:basic:read` 또는 `member:email:read`도 있을 때만 표시됩니다.

## 웹훅

네이티브 인보이스는 `pay_` ID에 대한 결제 웹훅을 보냅니다. `invoice.*` 이벤트는 레거시 인보이스 API에 속하며, 네이티브 인보이스는 이를 보내지 않습니다.

| 이벤트 | 발생 시점 |
| - | - |
| `payment.created` | 인보이스를 발행할 때. 초안은 아무것도 보내지 않습니다. |
| `payment.succeeded` | 인보이스가 결제될 때. 이 이벤트에서 주문을 처리하세요. |

`payment.failed` 같은 다른 `payment.*` 이벤트도 결제 시도가 변경됨에 따라 인보이스의 `pay_` ID에 대해 도착할 수 있습니다. [웹훅 가이드](https://docs.whop.com/ko/developer/guides/webhooks.md)에서 구독하세요.

주문을 처리하려면 초안을 만들 때 인보이스의 `id`를 주문과 함께 저장하세요. `payment.succeeded` 이벤트의 `data`는 결제이므로 `data.id`가 인보이스의 `pay_` ID입니다. [이벤트를 확인](https://docs.whop.com/ko/developer/guides/webhooks.md#verify-and-handle-events)한 후 해당 ID로 주문을 조회하세요. 이 핸들러에서 `orders`는 자체 주문 저장소를 나타냅니다:

```typescript TypeScript theme={null}
export async function handleWhopEvent(event: { type: string; data: { id: string } }) {
	if (event.type !== "payment.succeeded") return;

	const order = await orders.findByInvoiceId(event.data.id);
	if (!order || order.fulfilled) return;

	await orders.fulfill(order.id);
}
```

```python Python theme={null}
def handle_whop_event(event):
    if event["type"] != "payment.succeeded":
        return

    order = orders.find_by_invoice_id(event["data"]["id"])
    if order is None or order.fulfilled:
        return

    orders.fulfill(order.id)
```

`fulfilled`를 확인하면 재전달된 이벤트로 인해 주문이 두 번 처리되는 것을 막을 수 있습니다. 구독 갱신은 고유한 `pay_` ID를 가지므로 인보이스와 일치하지 않습니다.

## 인보이스 결제에 대한 결제 규칙

[결제 규칙](https://docs.whop.com/ko/developer/guides/manage-fraud.md)은 다른 체크아웃과 마찬가지로 Whop 자체의 사기 심사 후에 인보이스 결제에서 실행됩니다. 규칙이 할 수 있는 일은 고객이 참여하는지 여부에 따라 달라집니다.

* **발행 시 자동 청구는 오프세션입니다.** `block` 규칙은 이를 거절하고, `allow` 규칙은 다른 규칙에서 이를 면제합니다. `review` 및 `enforce_3ds` 규칙은 청구가 오프세션이므로 건너뜁니다.
* **체크아웃 링크를 통한 결제는 온세션입니다.** [사기 관리](https://docs.whop.com/ko/developer/guides/manage-fraud.md)의 적격성 제한과 함께 네 가지 액션이 모두 적용됩니다.

자동 청구에서 카드 조건은 저장된 결제 수단을, 청구 조건은 인보이스의 청구 주소를 읽습니다. `customer_email`은 고객의 Whop 계정 이메일입니다. 결제의 `payment_rule_matches`에는 결정을 내린 규칙이 나열됩니다. 건너뛴 규칙은 나열되지 않습니다.

## 대시보드의 인보이스

**Invoices** 페이지에서 네이티브 인보이스를 나열하고, 생성하고, 전송합니다. 레거시 인보이스는 **Legacy invoices** 탭에 있으며, [인보이스 보내기](https://docs.whop.com/ko/payments/send-an-invoice.md)에서 다룹니다.

## 권한

| 호출 | 권한 |
| - | - |
| [생성](https://docs.whop.com/ko/api-reference/invoices/create-invoice.md), [업데이트](https://docs.whop.com/ko/api-reference/invoices/update-invoice.md), [발행](https://docs.whop.com/ko/api-reference/invoices/issue-invoice.md), [전송](https://docs.whop.com/ko/api-reference/invoices/send-invoice.md), [예약 전송 취소](https://docs.whop.com/ko/api-reference/invoices/cancel-scheduled-send.md), [무효화](https://docs.whop.com/ko/api-reference/invoices/void-invoice.md), 또는 [회수 불가로 표시](https://docs.whop.com/ko/api-reference/invoices/mark-invoice-uncollectible.md) | `payment:charge` |
| [목록 조회](https://docs.whop.com/ko/api-reference/invoices/list-invoices.md), [조회](https://docs.whop.com/ko/api-reference/invoices/retrieve-invoice.md), 또는 [PDF 생성](https://docs.whop.com/ko/api-reference/invoices/generate-invoice-pdf.md) | `payment:basic:read` |

모든 쓰기 작업에는 [Create Payment](https://docs.whop.com/ko/api-reference/payments/create-payment.md)와 동일한 권한인 `payment:charge`가 필요하고, 모든 읽기 작업에는 `payment:basic:read`가 필요합니다. `invoice:*` 권한은 레거시 인보이스 API에 속하며 네이티브 인보이스는 이를 사용하지 않습니다. 인라인 `plan` 항목을 보내는 생성 또는 업데이트에는 `plan:create`도 필요합니다.

일부 필드에는 자체 권한이 필요합니다. 권한이 없으면 필드는 `null`로 반환되고, `recipient_emails`는 비어 있는 상태로 반환됩니다.

| 권한 | 공개되는 필드 |
| - | - |
| `member:basic:read` | `member_id`, `customer_name` |
| `member:email:read` | `email_address`, `recipient_emails` |
| `payment:basic:read` | `payment_method_id`, `mailing_address_id`, `billing_address` |
| `payment:charge` | `checkout_link` |

`POST` 후 자격 증명이 이러한 읽기 권한 중 하나를 잃으면, 저장된 응답에 해당 필드가 표시되는 경우 같은 `Idempotency-Key`로 재생하는 요청은 `error.code`가 `invoice_replay_permission_revoked`인 `403`으로 거부됩니다. 대신 `GET`으로 인보이스를 가져오세요. [권한 가이드](https://docs.whop.com/ko/developer/guides/permissions.md)에서 권한을 추가하세요.

## 오류

거부는 `{ error: { type, message, code } }`로 반환됩니다. 아래의 모든 코드는 별도로 명시하지 않는 한 `400`입니다. 알 수 없는 `plan_id`, `member_id`, `mailing_address_id`, `payment_method_id`는 `404`이며, Whop이 읽을 수 없는 타임스탬프는 `invalid_timestamp`가 포함된 `400`입니다.

다음 거부는 `error.code`가 없는 `400`이므로, 이유는 `error.message`에서 확인하세요:

* 알 수 없는 최상위 필드.
* 1\~999,999 범위를 벗어난 `quantity`.
* `recipient_emails`의 잘못된 주소 또는 50개 초과.
* 청구 주기 불일치 같은 여러 항목 규칙 위반.

### 생성 및 업데이트 오류

| `error.code` | 이유 |
| - | - |
| `invoice_item_count_invalid`, `invoice_item_invalid` | `items`에 1\~50개의 항목이 없거나, 항목에 `plan_id`와 `plan` 중 정확히 하나가 없습니다. |
| `invoice_plan_account_mismatch`, `invoice_plan_duplicated`, `invoice_currency_mismatch` | 변형이 다른 계정에 속하거나, 두 번 나타나거나, 나머지와 다른 통화를 사용합니다. |
| `invoice_quantity_unsupported` | 여러 수량을 허용하지 않는 변형의 `quantity`가 1보다 큽니다. |
| `invoice_plan_type_unsupported`, `invoice_legacy_plan_unsupported` | 변형이 즉시 구매가 아니거나 레거시 인보이스에 속합니다. |
| `invoice_installment_count_mismatch` | 인보이스의 반복 항목이 서로 다른 결제 횟수 후에 중지됩니다. |
| `invoice_recurring_plan_product_required` | 반복 변형에 상품이 없습니다. |
| `invoice_plan_unavailable`, `invoice_plan_archived`, `invoice_plan_currency_changed` | 변형이 삭제 또는 보관되었거나, 저장된 변형의 통화가 변경되었습니다. `items`를 다시 보내세요. |
| `invoice_customer_ambiguous`, `invoice_address_ambiguous` | `member_id`와 `email_address`를 둘 다 보냈거나, `billing_address`와 `mailing_address_id`를 둘 다 보냈습니다. |
| `invoice_address_properties_invalid`, `invoice_address_incomplete`, `invoice_address_country_invalid` | `billing_address`에 알 수 없는 필드가 있거나, 필수 필드가 누락되었거나, `country`가 유효한 코드가 아닙니다. |
| `invoice_address_member_required`, `invoice_member_mismatch`, `invoice_address_mismatch`, `invoice_payment_method_mismatch` | 주소에 고객이 없거나, 멤버, 주소 또는 결제 수단이 다른 사람의 것입니다. |
| `invoice_payment_method_unsupported` | 저장된 결제 수단으로 인보이스를 결제할 수 없습니다. |
| `invoice_buyer_fee_invalid`, `invoice_metadata_invalid`, `invoice_recipients_invalid` | `buyer_fee_percentage`가 범위를 벗어났거나, `metadata` 값이 문자열이 아니거나, `recipient_emails`가 배열이 아닙니다. |
| `invoice_not_editable`, `invoice_recipients_not_editable` | 인보이스가 초안이 아니거나, `recipient_emails` 변경이 초안, `open`, `uncollectible`이 아닌 인보이스에 도달했습니다. |
| `invoice_scheduled_not_editable`, `invoice_scheduled_recipients_required` | 초안에 예약 전송이 있습니다. 편집하기 전이나 마지막 수신자를 제거하기 전에 취소하세요. |

### 발행 오류

| `error.code` | 이유 |
| - | - |
| `invoice_not_issuable` | 인보이스가 초안이나 `open`이 아닙니다. |
| `invoice_recipient_required` | 인보이스에 고객이 없습니다. |
| `invoice_account_verification_required` | 계정이 인증을 완료하지 않았습니다. |
| `invoice_account_suspended` | 계정이 정지되었습니다. |
| `invoice_items_required`, `invoice_items_changed`, `invoice_plan_unavailable`, `invoice_plan_archived` | 인보이스에 항목이 없거나, 변형이 삭제, 보관되었거나 계정, 통화, 상품이 변경되었습니다. 항목을 업데이트하세요. |
| `invoice_tax_address_required` | 세금이 적용되는데 Whop이 고객의 위치를 알 수 없습니다. 청구 주소를 추가하세요. |
| `invoice_tax_unresolved` | 세금을 계산할 수 없습니다. |
| `invoice_changed_during_issuance`, `invoice_changed_during_calculation` | 세금을 계산하는 동안 인보이스가 변경되었습니다. 다시 발행하세요. |
| `invoice_payment_method_unavailable`, `invoice_payment_method_unsupported`, `payment_method_unavailable` | 저장된 결제 수단이 고객에게서 제거되었거나, 인보이스를 결제할 수 없거나, 더 이상 작동하지 않습니다. |
| `out_of_stock` | 저장된 결제 수단에 청구할 때만: 변형의 재고가 인보이스 수량에 비해 부족합니다. |
| `payment_fees_unavailable` | 저장된 결제 수단에 청구할 때만: 결제 수수료를 준비할 수 없습니다. |

### 전송 및 예약 오류

초안을 전송하면 발행되므로, 전송은 [발행 오류](#issue-errors)의 어떤 이유로든 거부될 수 있습니다.

| `error.code` | 이유 |
| - | - |
| `invoice_not_sendable` | 인보이스가 초안이나 `open`이 아닙니다. |
| `invoice_send_recipients_required` | 인보이스에 `recipient_emails`가 없고 청구할 것도 없습니다. |
| `invoice_payment_link_unavailable` | 이메일로 보낼 결제 링크가 없습니다. `open` 인보이스에 `checkout_link`가 없거나, 저장된 결제 수단이 없는 초안이 비즈니스 구매자에게 청구됩니다. |
| `invoice_send_limit_reached` | `429`: 인보이스가 지난 24시간 동안 이미 세 번 이메일로 전송되었습니다. |
| `invoice_not_schedulable` | 초안만 예약할 수 있습니다. |
| `invoice_scheduled_send_in_past` | `send_at`이 미래가 아닙니다. |

### 기타 오류

| `error.code` | 이유 |
| - | - |
| `invoice_not_uncollectible` | `open` 인보이스만 회수 불가로 표시할 수 있습니다. |
| `invoice_replay_permission_revoked` | `403`: 멱등성 재생이 자격 증명으로 더 이상 읽을 수 없는 필드를 표시하게 됩니다. |

결제된 인보이스를 무효화하면 코드 없는 `400`이 반환됩니다.

## 다음 단계

> [card] [인보이스 API 레퍼런스](https://docs.whop.com/ko/api-reference/invoices/create-invoice.md)
>
> 모든 인보이스 엔드포인트, 매개변수, 응답 필드.

> [card] [결제 수단 저장](https://docs.whop.com/ko/developer/guides/save-payment-methods.md)
>
> 인보이스가 발행 시 청구하는 저장된 결제 수단을 수집하세요.

> [card] [사기 관리](https://docs.whop.com/ko/developer/guides/manage-fraud.md)
>
> 인보이스 결제를 심사하는 결제 규칙을 작성하세요.

> [card] [웹훅 수신하기](https://docs.whop.com/ko/developer/guides/webhooks.md)
>
> 인보이스의 `payment.created`와 `payment.succeeded`를 추적하세요.


## Related topics

- [레거시 인보이스에서 마이그레이션하기](https://docs.whop.com/ko/developer/guides/migrate-from-legacy-invoices.md)
- [Invoices API](https://docs.whop.com/ko/api-reference/invoices/invoice.md)
- [Legacy Invoice](https://docs.whop.com/ko/api-reference/legacy/invoices/legacy-invoice.md)
