> ## 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에서 네이티브 인보이스로 이동하세요: API 버전을 전환하고, 항목을 중심으로 요청을 재구성하고, 필드, 상태, 웹훅을 매핑하세요.

네이티브 인보이스는 레거시 인보이스와 동일한 `/invoices` 경로를 사용하지만 요청 형식과 수명 주기가 다릅니다. 이 가이드는 통합을 마이그레이션할 때 변경해야 하는 필드와 작업을 매핑합니다.

> [!NOTE]
>
> 공유 경로는 `Api-Version-Date: 2026-10-24`부터 네이티브 인보이스로 라우팅됩니다.
> 아래 네이티브 예제는 현재 변형 필드 이름과 고객 고정 규칙이 적용된
> `Api-Version-Date: 2026-11-02-1`을 사용합니다. 각 네이티브 요청에 이 헤더를
> 보내세요. 레거시 호출은 `2026-10-15-1`과 같은 이전 릴리스 버전으로 유지하세요.
> 헤더가 자격 증명 고정 버전을 재정의하는 방식은 [API 버전](https://docs.whop.com/ko/developer/api/versioning.md)에서
> 설명합니다.

## 변경 사항

| | 레거시 인보이스 | 네이티브 인보이스 |
| - | - | - |
| **ID** | `inv_` | 인보이스의 결제와 동일한 `pay_` |
| **청구 대상** | 하나의 요금제와, 합산하면 해당 가격이 되는 선택적 라벨 | 1\~50개의 항목. 각 항목은 기존 변형이거나 인라인으로 찾거나 생성한 변형 |
| **생성** | `save_as_draft` 또는 `automatically_finalizes_at`이 설정되지 않은 한 한 번의 호출로 확정 | 항상 초안으로 저장됩니다. 이후 발행하거나 전송합니다. |
| **금액** | 요금제의 가격 | `subtotal`, `buyer_fee_amount`, `tax_amount`, `total`, `amount_due` |
| **결제 페이지** | URL인 `pay_online_url` | 체크아웃을 여는 데 사용하는 서명된 토큰인 `checkout_link` |
| **연체** | `status: past_due` | `open` 또는 `uncollectible` 인보이스의 `overdue: true` |
| **웹훅** | `invoice.*` | 인보이스의 `pay_` ID에 대한 결제 이벤트 |

네이티브 API는 레거시 `inv_` 인보이스를 나열하거나 조회하지 않습니다. 기존 레거시 인보이스는 이전 API 버전으로 계속 조회하세요. 네이티브 인보이스를 생성하면 별도의 청구서가 만들어집니다. 레거시 인보이스를 변환하거나 정산하지 않습니다.

## 마이그레이션 전 확인 사항

흐름을 옮기기 전에 다음 차이점을 확인하세요. 네이티브 API가 제공하지 않는 기능이 필요한 흐름은 레거시 API에 그대로 두세요.

| 레거시 기능 | 네이티브 동작 |
| - | - |
| `invoice.*` 웹훅 | 네이티브 인보이스는 결제 이벤트를 사용합니다. 일부 레거시 이벤트에는 직접 대응하는 이벤트가 없습니다. [웹훅 매핑](#map-webhooks)을 참조하세요. |
| Whop 외부에서 돈을 받은 후 인보이스를 결제 완료로 표시 | 네이티브 `mark_paid` 엔드포인트가 없습니다. |
| 초안 삭제 | 네이티브 `DELETE /invoices/{id}`가 없습니다. 무효화하면 인보이스 기록과 번호가 유지됩니다. |
| `plan.payment_method_configuration` | 인보이스 요청은 이 필드를 허용하지 않습니다. 대신 기존 변형 또는 계정의 결제 수단을 구성하세요. |
| 정기 요금제의 무료 체험 및 초기 수수료 | `2026-11-11`부터 인보이스에 초기 수수료가 추가됩니다. 이전 버전은 갱신 가격을 청구하므로 수수료를 일회성 항목으로 추가하세요. 변형의 체험 기간이 적용됩니다. |
| `subscription_billing_anchor_at` | 인보이스에 `subscription_starts_at`을 보내세요. 인보이스가 결제될 때 이미 지난 시간이면 결제 시점에 기간이 시작됩니다. 이전과 마찬가지로 무료 체험을 건너뜁니다. |
| 임의의 `line_items` 라벨, 소수 수량 또는 음수 크레딧 | 네이티브 라인은 변형을 청구합니다. 수량은 양의 정수여야 하며 라벨은 상품 또는 변형 제목에서 가져옵니다. 세부 내역을 복사하지 말고 청구 항목을 재구성하세요. |
| 레거시 인보이스의 `current_plan.id` 재사용 | 네이티브 인보이스는 레거시 인보이스에 연결된 변형을 거부합니다. 별도의 변형을 사용하거나 인라인으로 생성하세요. |

## 생성 요청 매핑하기

레거시 생성은 하나의 요금제와 선택적으로 가격을 나누는 라벨을 보냅니다. 네이티브 생성은 청구되는 각 변형에 대한 항목을 보냅니다.

이 예제는 항목 가격 합계를 19.99 USD로 설정합니다. 기존 네이티브 변형은 15 USD 설정 요금을 나타냅니다. 4.99 USD 서비스 수수료는 상품이 없는 사용자 지정 일회성 요금입니다. 두 API 모두 통화 단위로 가격을 받습니다. 4.99 USD에는 `4.99`를 사용하세요. `499`를 보내면 499 USD가 청구됩니다.

```json Legacy theme={null}
{
	"account_id": "biz_xxxxxxxxxxxxxx",
	"product_id": "prod_xxxxxxxxxxxxx",
	"member_id": "mber_xxxxxxxxxxxxx",
	"collection_method": "send_invoice",
	"due_date": "2026-12-01T00:00:00Z",
	"plan": {
		"plan_type": "one_time",
		"initial_price": 19.99,
		"currency": "usd"
	},
	"line_items": [
		{ "label": "Setup", "quantity": 1, "unit_price": 15 },
		{ "label": "Service fee", "quantity": 1, "unit_price": 4.99 }
	]
}
```

```json Native theme={null}
{
	"account_id": "biz_xxxxxxxxxxxxxx",
	"member_id": "mber_xxxxxxxxxxxxx",
	"due_at": "2026-12-01T00:00:00Z",
	"items": [
		{ "variant_id": "plan_xxxxxxxxxxxxx", "quantity": 1 },
		{
			"variant": {
				"title": "Service fee",
				"billing_type": "one_time",
				"initial_price": 4.99,
				"currency": "usd"
			}
		}
	]
}
```

네이티브 요청은 초안을 생성합니다. 발행하고 이메일로 보내려면 `POST /invoices/{id}/send`로 전송하세요. `member_id`는 구독(`mem_`)이 아닌 고객(`mber_`)을 식별합니다.

| 레거시 필드 | 네이티브 필드 | 참고 |
| - | - | - |
| `account_id` | `account_id` | 인보이스를 발행하는 계정입니다. |
| `plan` | `items` | 각 항목은 `variant_id` 또는 인라인 `variant`와 선택적 `quantity`를 받습니다. 모든 항목은 동일한 통화를 사용합니다. |
| `product`, `product_id` | `items[].variant.product`, `items[].variant.product_id` | 둘 중 하나를 사용하세요. 인라인 `product`에는 `external_identifier`와 `title`이 필요합니다. 정기 변형에는 상품이 필요합니다. 일회성 사용자 지정 요금은 생략할 수 있습니다. |
| `line_items` | `items` | 청구 라인을 변형으로 재구성하세요. `quantity`의 기본값은 1입니다. 1보다 큰 값에는 여러 수량을 허용하는 변형이 필요합니다. |
| `collection_method` | `payment_method_id`, 이후 발행 또는 전송 | 자동 청구에는 저장된 결제 수단을 설정하고, 체크아웃을 통한 결제에는 생략하세요. [발행, 전송 및 청구](#issue-send-and-charge)를 참조하세요. |
| `save_as_draft` | 없음 | 생성 시 항상 초안으로 저장됩니다. |
| `automatically_finalizes_at` | Send Invoice의 `send_at` | 예약된 전송 시점까지 발행을 지연합니다. `charge_at`은 발행이 아닌 저장된 결제 수단 청구를 지연합니다. |
| `due_date` | `due_at` | ISO 8601 타임스탬프를 보내세요. |
| `charge_buyer_fee` | `buyer_fee_percentage` | `false`는 `0`으로, 레거시 `true` 수수료는 `5`로 매핑하세요. 그 외 0이 아닌 비율은 5에서 100 사이여야 하며 소수점 이하 최대 두 자리까지 허용됩니다. |
| `payment_method_id`, `payment_token_id` | `payment_method_id` | `payt_` 접두사가 붙은 고객의 저장된 결제 수단 중 하나입니다. 설정하려면 `payment:charge`가 필요합니다. |
| `member_id`, `email_address`, `customer_name` | 생성 시 동일 | `member_id` 또는 `email_address` 중 하나만 선택하세요. 네이티브 인보이스는 청구 대상 고객과 별개로 `recipient_emails`도 받습니다. |
| `mailing_address_id`, `billing_address` | 이름은 같지만 주소 입력 범위가 더 좁음 | 하나를 선택하세요. 인라인 주소에는 `line1`, `city`, `postal_code`, `country`가 필요합니다. `name`, `line2`, `state`, `phone`도 허용합니다. 레거시 `tax_id_type` 또는 `tax_id_value` 필드는 허용하지 않습니다. |
| `subscription_billing_anchor_at` | `subscription_starts_at` | 첫 번째 청구 기간이 시작되는 시점입니다. 미래 시점이어야 하며 정기 항목이 필요합니다. |
| 없음 | `memo`, `metadata` | `memo`는 이메일, PDF, 체크아웃에 표시됩니다. `metadata`는 문자열 키-값 쌍을 저장합니다. |

`2026-10-27-2` 이전의 네이티브 버전에서는 `variant_id`, `variant`, `billing_type` 대신 `plan_id`, `plan`, `plan_type`을 사용하세요. 이러한 이전 버전에서는 응답의 라인 항목도 `plan_id`를 사용합니다.

### 발행된 금액 고정 유지하기

`PATCH /invoices/{id}`는 초안의 항목과 청구 세부 정보를 편집합니다. `items`를 보내면 변형의 현재 가격을 사용하여 전체 목록이 교체됩니다. 생략하면 저장된 항목과 가격이 유지됩니다.

* 항목이나 청구 세부 정보를 편집하기 전에 예약된 전송을 취소하세요.
* `2026-11-02-1`부터는 초안에 지정된 고객을 교체하거나 지울 수 없습니다. 고객이 없는 초안에는 여전히 고객을 지정할 수 있습니다. 다른 사람에게 새 인보이스를 만들기 전에 초안을 무효화하세요.
* `email_address`와 `customer_name`은 생성 시에만 입력할 수 있습니다.
* 발행된 금액과 항목은 고정됩니다. `memo` 및/또는 `recipient_emails`만 포함한 업데이트는 예약된 초안을 포함한 `draft`, `open`, `uncollectible` 인보이스에서 허용됩니다.

## 발행, 전송 및 청구

레거시 생성은 `collection_method`로 수금 방식을 선택합니다. 네이티브 인보이스는 초안을 생성한 후 별도의 호출을 사용합니다:

1. 초기 인보이스 이메일을 보내지 않고 최종 세금을 계산하여 결제를 위해 열려면 `POST /invoices/{id}/issue`로 **발행하세요**.
2. **또는 `POST /invoices/{id}/send`로 전송하세요.** 이렇게 하면 초안이 발행됩니다. 저장된 결제 수단으로 즉시 청구하지 않는 한 수신자에게 이메일을 보냅니다. `open` 인보이스를 전송하면 이메일이 다시 발송됩니다. `send_at`은 초안의 전송을 예약합니다. `POST /invoices/{id}/unschedule`은 해당 예약을 취소합니다.
3. 초안에 `payment_method_id`를 설정하여 **저장된 결제 수단으로 청구하세요**. 합계가 양수이면 발행 또는 전송 시 미래의 `charge_at`에, 없으면 미래의 `due_at`에, 그것도 없으면 즉시 청구합니다. `charge_at`은 미래 시점이어야 하며 `send_at`보다 앞설 수 없습니다.

즉시 청구하는 초안을 전송하면 초기 인보이스 이메일을 건너뜁니다. 나중에 청구하도록 전송하면 지금 이메일을 보냅니다. 자동 청구가 실패하면 Issue Invoice를 사용한 경우에도 결제 링크 이메일이 발송될 수 있습니다. [저장된 결제 수단으로 청구하기](https://docs.whop.com/ko/developer/guides/invoices.md#charge-a-saved-payment-method)에서 흐름을 설명합니다.

`open` 응답은 결제를 확인하지 않습니다. 주문을 처리하기 전에 `payment.succeeded`를 기다리세요. 열린 인보이스를 청구하거나 재시도하려면 [Charge Invoice](https://docs.whop.com/ko/api-reference/invoices/charge-invoice.md)를 사용하세요. 다시 발행하거나 전송해도 새 청구가 시작되지 않습니다.

정기 변형의 경우 Issue Invoice 또는 Send Invoice의 `collection_method`가 **갱신**을 제어합니다. `charge_automatically`는 향후 결제를 자동으로 수금합니다. `send_invoice`는 매 기간 새 인보이스를 만들어 이메일로 보냅니다. 첫 번째 인보이스 수금을 위한 `payment_method_id`를 대체하지 않습니다. [구독 인보이스 발행하기](https://docs.whop.com/ko/developer/guides/invoices.md#invoice-a-subscription)를 참조하세요.

## 응답 매핑하기

| 레거시 필드 | 네이티브 필드 | 참고 |
| - | - | - |
| `id` (`inv_`) | `id` (`pay_`) | `object`는 `invoice`입니다. 동일한 ID가 결제를 식별합니다. |
| `current_plan` 가격 | `subtotal`, `buyer_fee_amount`, `tax_amount`, `total`, `amount_due` | 금액 객체에는 소수 문자열 `amount`, `currency`, `decimals`, `display_decimals`가 포함됩니다. `totals_status`는 초안에서 `estimated`, 그 외에는 `final`입니다. |
| `company.id` | `account_id` | ID로 계정을 조회하세요. |
| `product.id`, `current_plan.id` | `line_items[].product_id`, `line_items[].variant_id` | 각 청구 라인은 상품과 변형을 식별합니다. 사용자 지정 요금에는 상품이 없을 수 있습니다. |
| `member.id` | `member_id` | `mber_` 접두사가 붙은 고객 ID입니다. `member:basic:read`가 필요합니다. |
| `user` | 최상위 사용자 필드 없음 | 멤버를 조회하여 사용자를 찾으세요. `membership_id`(`mem_`)는 고객이 아닌 멤버십을 식별합니다. |
| `mailing_address` | `billing_address`, `mailing_address_id` | 인라인 주소는 객체로 유지됩니다. |
| `payment.id` | 인보이스 자체의 `id` | 동일한 `pay_` ID로 `GET /payments/{id}`를 사용하여 결제 세부 정보를 조회하세요. |
| `number` | `number`, `invoice_prefix` | 형식이 지정된 번호와 계정 접두사입니다. |
| `due_date` | `due_at` | ISO 8601 타임스탬프 또는 `null`입니다. |
| `automatically_finalizes_at` | `scheduled_send_at` | `scheduled_charge_at`은 계획된 저장 결제 수단 청구를 표시합니다. `scheduled_collection_method`는 예약된 전송의 갱신 수금 선택을 표시합니다. |
| `charge_buyer_fee` | `buyer_fee_percentage`, `buyer_fee_amount` | 비율과 계산된 금액입니다. |
| `customer_name`, `email_address` | 동일 | `recipient_emails`도 추가됩니다. 이 필드들은 권한으로 제한됩니다. |
| `pay_online_url` | `checkout_link` | URL이 아닌 서명된 토큰입니다. [인보이스 체크아웃 열기](#open-the-invoice-checkout)를 참조하세요. |
| `line_items` | `line_items` | 라인에는 `variant_id`, `product_id`, `label`, `description`, `quantity`, `unit_amount`, `subtotal`, `discount_amount`, `tax_amount`가 있습니다. |
| `status` | `status`, `overdue` | [상태 매핑](#map-statuses)을 참조하세요. |
| `payment_processing` | `status` 및 결제 세부 정보 | 결제가 정산되는 동안 `pending`을 처리하세요. `paid_at`은 결제 완료를 기록합니다. 처리 중 플래그가 아닙니다. |
| `fetch_invoice_token` | 직접적인 대응 항목 없음 | 인증된 인보이스 조회, 체크아웃에는 `checkout_link`, PDF에는 Generate Invoice PDF를 사용하세요. |
| 없음 | `paid_at`, `memo`, `metadata` | 결제 완료 시간, 고객 메모, 메타데이터입니다. |

PDF를 다운로드하려면 `POST /invoices/{id}/generate_pdf`를 호출하여 단기 링크를 받으세요.

### 인보이스 체크아웃 열기

`checkout_link`에는 `.`으로 구분된 인보이스 ID와 서명된 토큰이 포함되어 있습니다. 이 인보이스에 대한 세션을 열려면 전체 값을 `link`로 `POST /checkout_sessions`에 전달하세요. 고객용 URL은 [호스팅 체크아웃 URL 만들기](https://docs.whop.com/ko/developer/guides/invoices.md#get-the-checkout-link)를 따르세요.

이 필드는 체크아웃이 가능한 동안에만 존재하며, 인보이스가 `open` 상태여야 합니다. 기업 구매자와 취소된 멤버십은 이 체크아웃을 사용할 수 없습니다. 키에는 `payment:charge`가 필요하며, 인보이스에 저장된 결제 수단이 없는 경우 `invoice:create`/`invoice:update`가 필요합니다. 초안, 결제 완료, 무효, 회수 불능 인보이스와 기업 구매자의 경우 `null`입니다.

## 상태 매핑하기

| 레거시 `status` | 네이티브 |
| - | - |
| `draft` | `draft` |
| `open` | `open` |
| `past_due` | `open` 또는 `uncollectible`, `overdue: true` 포함 |
| `paid` | `paid` |
| `uncollectible` | `uncollectible` |
| `void` | `void` |

네이티브 인보이스는 `authorized`, `pending`, `unresolved`도 반환할 수 있습니다. 레거시 열거형 외의 모든 상태를 결제 완료 또는 실패로 처리하지 마세요. [상태 및 수명 주기](https://docs.whop.com/ko/developer/guides/invoices.md#statuses-and-lifecycle)에서 이를 설명합니다.

## 엔드포인트 매핑하기

| 레거시 | 네이티브 |
| - | - |
| `GET /invoices` | `overdue` 필터가 있는 [List Invoices](https://docs.whop.com/ko/api-reference/invoices/list-invoices.md) |
| `GET /invoices/{id}` | [Retrieve Invoice](https://docs.whop.com/ko/api-reference/invoices/retrieve-invoice.md) |
| `POST /invoices` | 초안을 저장하는 [Create Invoice](https://docs.whop.com/ko/api-reference/invoices/create-invoice.md) |
| `PATCH /invoices/{id}` | 위의 초안 및 발행된 인보이스 규칙이 적용되는 [Update Invoice](https://docs.whop.com/ko/api-reference/invoices/update-invoice.md) |
| `POST /invoices/{id}/resend` | [Send Invoice](https://docs.whop.com/ko/api-reference/invoices/send-invoice.md) |
| `POST /invoices/{id}/void` | [Void Invoice](https://docs.whop.com/ko/api-reference/invoices/void-invoice.md) |
| `POST /invoices/{id}/mark_uncollectible` | [인보이스를 회수 불능으로 표시](https://docs.whop.com/ko/api-reference/invoices/mark-invoice-uncollectible.md) |
| `DELETE /invoices/{id}` | 대응 항목 없음. 기록을 유지하면서 초안을 취소하려면 무효화하세요. |
| `POST /invoices/{id}/mark_paid` | 대응 항목 없음 |
| 없음 | [Issue Invoice](https://docs.whop.com/ko/api-reference/invoices/issue-invoice.md), [Cancel Scheduled Send](https://docs.whop.com/ko/api-reference/invoices/cancel-scheduled-send.md), [Charge Invoice](https://docs.whop.com/ko/api-reference/invoices/charge-invoice.md), [List Invoice Sends](https://docs.whop.com/ko/api-reference/invoices/list-invoice-sends.md), [Generate Invoice PDF](https://docs.whop.com/ko/api-reference/invoices/generate-invoice-pdf.md) |

## 웹훅 매핑하기

네이티브 인보이스는 `pay_` ID에 대한 결제 이벤트를 보냅니다. `invoice.*` 이벤트는 레거시 인보이스를 설명합니다.

| 레거시 이벤트 | 네이티브 동작 |
| - | - |
| `invoice.created` | 초안이 생성될 때가 아닌 발행될 때 `payment.created` |
| `invoice.paid` | `payment.succeeded` |
| `invoice.past_due` | `overdue`를 읽거나 이를 기준으로 필터링하세요. 일치하는 연체 결제 이벤트는 없습니다. |
| `invoice.voided`, `invoice.marked_uncollectible` | 인보이스의 `status`를 읽으세요. 이러한 전환을 직접 대체하는 결제 이벤트는 없습니다. |

결제 이벤트는 인보이스와 관련 없는 결제도 포함합니다. 이벤트의 결제 ID를 저장한 네이티브 인보이스 ID와 대조하세요. [웹훅](https://docs.whop.com/ko/developer/guides/invoices.md#webhooks)에서 `payment.succeeded`로 주문을 처리하는 방법을 보여 줍니다.

## 권한

| 작업 | 필요한 권한 |
| - | - |
| 저장된 결제 수단 없이 초안 생성 | `invoice:create` 또는 `payment:charge` |
| 저장된 결제 수단이나 예약된 전송 없이 초안 업데이트 | `invoice:update`, `invoice:create` 또는 `payment:charge` |
| 저장된 결제 수단 없이 초안 전송 또는 예약, 또는 예약된 전송 취소 | `invoice:update`, `invoice:create` 또는 `payment:charge` |
| 저장된 결제 수단 설정, 저장된 결제 수단이 있는 인보이스 작성, 발행, 청구, 무효화 또는 회수 불능 표시 | `payment:charge` |
| 예약된 초안 업데이트, 또는 발행된 인보이스 업데이트나 재전송 | `payment:charge` |
| 목록 조회, 조회, PDF 생성 또는 이메일 전송 목록 조회 | `payment:basic:read` |
| 인라인 `variant` 제공 | `plan:create`도 필요 |
| 인라인 `product` 생성 또는 업데이트 | 각각 `access_pass:create` 또는 `access_pass:update`도 필요 |

`member:basic:read`는 고객 이름과 멤버/멤버십 ID를 노출합니다. `member:email:read`는 `email_address`와 `recipient_emails`를 노출합니다. 결제 수단 및 주소 필드에는 `payment:basic:read`가 필요합니다.

## 마이그레이션 체크리스트

1. 레거시 API에 남아 있어야 하는 워크플로는 [마이그레이션 전 확인 사항](#before-you-migrate)을 확인하세요.
2. 네이티브 호출을 해당 필드 이름과 일치하는 릴리스 버전(이 예제의 경우 `2026-11-02-1`)으로 고정하세요.
3. 수량, 가격, 통화, 상품 요구 사항을 확인하면서 적격 변형으로 `items`를 구성하세요.
4. 레거시의 단일 호출 생성을 생성 후 발행 또는 전송으로 대체하세요. 첫 번째 인보이스에는 저장된 결제 수단 청구를, 갱신에는 수금 방식을 선택하세요.
5. 기한, 예약된 전송, 구매자 수수료는 필드 이름만이 아니라 동작에 따라 매핑하세요.
6. 네이티브 `pay_` ID와 레거시 `inv_` ID를 구분하세요. 레거시 조회는 이전 버전으로 유지하세요.
7. 금액 객체에서 금액을 읽고, 서명된 `checkout_link`를 사용하여 체크아웃을 여세요.
8. `overdue`와 추가 결제 상태를 처리하세요.
9. 인보이스의 결제 ID에 대한 `payment.succeeded`로 주문을 처리하세요.
10. 인라인 변형/상품 및 고객 조회 권한을 포함하여 흐름에서 사용하는 권한을 부여하세요.

## 다음 단계

> [card] [인보이스 가이드](https://docs.whop.com/ko/developer/guides/invoices.md)
>
> 네이티브 인보이스를 생성, 발행, 전송하고 수금하세요.

> [card] [인보이스 API 레퍼런스](https://docs.whop.com/ko/api-reference/invoices/create-invoice.md)
>
> 모든 네이티브 인보이스 엔드포인트와 필드입니다.

> [card] [레거시 인보이스 API](https://docs.whop.com/ko/api-reference/legacy/invoices/legacy-invoice.md)
>
> 현재 통합에서 호출하는 엔드포인트입니다.

> [card] [API 버전](https://docs.whop.com/ko/developer/api/versioning.md)
>
> `Api-Version-Date`와 버전 고정의 작동 방식입니다.
