> ## 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 v2 또는 공개 GraphQL API에서 연동을 이전하세요. 각 경로나 작업에 대한 Current API 대체 항목과 동작이 다른 부분을 확인하세요.

Whop은 두 가지 이전 API를 종료합니다. 둘 다 동일한 API 키로 `https://api.whop.com/api/v1`의 Current API로 이전됩니다.

| 연동에서 호출하는 대상 | 작동 중단일 | 가이드 |
| - | - | - |
| `https://api.whop.com/api/v2` 또는 `https://api.whop.com/v2` | 2026년 11월 13일 | [API v2](#v2) |
| `https://api.whop.com/public-graphql` 또는 `@whop/api` 패키지 사용 | 2026년 10월 26일 | [공개 GraphQL](#public-graphql) |

## Current API로 전환하기

**1. API 키 유지하기**

Current API는 동일한 계정 및 앱 API 키를 사용합니다. 요청이 `403`을 반환하면 해당 엔드포인트에 필요한 권한이 키에 없는 것입니다. **Developer → API keys**에서 권한을 추가하거나 앱의 권한에서 요청하세요.

**2. SDK 설치 및 버전 고정하기**

공식 SDK는 Current API를 호출하며 빌드 기준이 된 API 버전을 전송합니다. `@whop/api`를 사용한다면 `@whop/sdk`로 교체하세요. `withUser` 및 `withCompany` 헬퍼에는 대응하는 기능이 없습니다. 대신 각 요청마다 사용자 또는 계정 ID를 전달하세요.

```typescript TypeScript theme={null}
import { WhopClient } from "@whop/sdk";

const client = new WhopClient({ token: process.env.WHOP_API_KEY });

const access = await client.users.checkAccess({
  id: "user_xxxxxxxxxxxxx",
  resource_id: "exp_xxxxxxxxxxxxx",
});
```

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

from whop_sdk import Whop

client = Whop(token=os.environ["WHOP_API_KEY"])

membership = client.memberships.retrieve("mem_xxxxxxxxxxxxx")
```

```bash cURL theme={null}
curl https://api.whop.com/api/v1/memberships/mem_xxxxxxxxxxxxx \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-08-21-1"
```

SDK 없이 API를 호출한다면 모든 요청에 `Api-Version-Date`를 전송하세요. [API 버전](https://docs.whop.com/ko/developer/api/versioning.md)에서 버전 고정을 설명합니다.

**3. 각 호출 교체하기**

이전하려는 API의 탭을 사용한 다음, 코드에서 이전 기본 URL이나 패키지를 제거하세요.

> [tab] API v2
>
> ### v2 호출 찾기
>
> 모든 v2 응답에는 세 가지 헤더가 포함됩니다:
>
> | 헤더 | 예시 | 의미 |
> | - | - | - |
> | `Deprecation` | `@1791417600` | Whop이 이 엔드포인트를 지원 중단했습니다. 값은 Unix 초 단위의 지원 중단 날짜입니다. |
> | `Sunset` | `Fri, 13 Nov 2026 00:00:00 GMT` | API v2는 2026년 11월 13일에 작동을 중단합니다. |
> | `Link` | `<https://api.whop.com/api/v1/memberships/mem_xxxxxxxxxxxxx>; rel="successor-version", <https://docs.whop.com/developer/api/migrate-from-previous-versions#v2>; rel="deprecation"` | `successor-version` URL은 이 요청을 대체하는 Current API 요청입니다. `deprecation` URL은 이 가이드입니다. |
>
> `Deprecation`이 포함된 응답을 기록하여 연동에서 아직 수행하는 모든 v2 호출을 찾으세요.
>
> ### 경로 매핑
>
> #### 멤버십 및 라이선스
>
> | v2 경로 | Current API | 참고 |
> | - | - | - |
> | `GET /memberships` | `GET /memberships` | 커서 페이지네이션. [페이지네이션](#pagination)을 참고하세요. `discord_id=<id>`를 `external_account=discord_<id>`로 바꾸세요. |
> | `GET /memberships/{id}` | `GET /memberships/{id}` | `mem_` ID 대신 라이선스 키도 받습니다. |
> | `POST /memberships/{id}` | `PATCH /memberships/{id}` | 키를 병합하려면 `metadata`를 전송하세요. 지우려면 `{}`를 전송하세요. |
> | `POST /memberships/{id}/cancel` | `POST /memberships/{id}/cancel` | 갱신일까지 액세스를 유지하려면 `cancel_at_period_end: true`를 전달하세요. |
> | `POST /memberships/{id}/terminate` | `POST /memberships/{id}/cancel` | 즉시 액세스를 취소하려면 `cancel_at_period_end`를 생략하세요. |
> | `POST /memberships/{id}/add_free_days` | `POST /memberships/{id}/extend` | |
> | `POST /memberships/{id}/validate_license` | `GET /memberships/{id}` 및 `PATCH /memberships/{id}` | 서버에서 키를 확인하고 기기를 연결하세요. [라이선스 키](#license-keys)를 참고하세요. |
> | `GET /licenses` | `GET /memberships` | 상품에 Software 앱이 포함된 경우 각 멤버십에 `license_key`가 있습니다. |
>
> #### 멤버 및 고객
>
> | v2 경로 | Current API | 참고 |
> | - | - | - |
> | `GET /members` | `GET /members` | |
> | `GET /customers` | `GET /members` | 고객과 멤버는 동일한 리소스입니다. |
> | `GET /members/{search}` | `GET /members` | `user_ids` 또는 `query`로 필터링하세요. `GET /members/{id}`는 `mber_` ID만 받습니다. Discord ID로 멤버를 찾으려면 `GET /memberships?external_account=discord_<id>`를 호출하고 각 멤버십의 `member_id`를 읽으세요. |
> | `GET /customers/{search}` | `GET /members` | 위와 동일합니다. |
>
> #### 결제 및 체크아웃
>
> | v2 경로 | Current API | 참고 |
> | - | - | - |
> | `GET /payments` | `GET /payments` | 필터는 `status`, `membership_id`처럼 단수형입니다. |
> | `GET /payments/{id}` | `GET /payments/{id}` | |
> | `POST /payments/{id}/refund` | `POST /payments/{id}/refund` | |
> | `GET /payment_fees?payment_id=` | `GET /payments/{id}/fees` | |
> | `GET /payment_methods` | `GET /payment_methods` | |
> | `POST /checkout_requests` | `POST /payments` | `member_id`(`mber_`)와 `payment_method_id`를 전달하세요. 응답은 결제입니다. |
> | `GET /checkout_requests/{id}` | `GET /payments/{id}` | `POST /payments`가 결제를 직접 반환하므로 폴링할 필요가 없습니다. |
> | `GET /checkout_sessions` | `GET /checkout_configurations` | 체크아웃 세션은 이제 체크아웃 구성이라고 부릅니다. |
> | `GET /checkout_sessions/{id}` | `GET /checkout_configurations/{id}` | |
> | `POST /checkout_sessions` | `POST /checkout_configurations` | 응답에 `purchase_url`이 포함됩니다. |
> | `DELETE /checkout_sessions/{id}` | `DELETE /checkout_configurations/{id}` | |
>
> #### 상품 및 플랜
>
> 플랜은 이제 변형(variant)이라고 부릅니다. 변형 ID는 `plan_` 접두사를 유지하므로 저장된 ID는 계속 작동합니다.
>
> | v2 경로 | Current API | 참고 |
> | - | - | - |
> | `GET /products`, `GET /access_passes` | `GET /products` | 액세스 패스는 이제 상품이라고 부릅니다. |
> | `GET /products/{id}`, `GET /access_passes/{id}` | `GET /products/{id}` | |
> | `POST /products/{id}`, `POST /access_passes/{id}` | `PATCH /products/{id}` | |
> | `GET /plans` | `GET /variants` | |
> | `GET /plans/{id}` | `GET /variants/{id}` | |
> | `POST /plans` | `POST /variants` | |
> | `POST /plans/{id}` | `PATCH /variants/{id}` | |
> | `POST /plans/{id}/create_quick_link` | `POST /variants` | `visibility: "quick_link"`, `stock`, `short_link`로 변형을 생성하세요. Current API는 기존 플랜을 복사하지 않으므로 가격 필드도 함께 전송하세요. |
> | `GET /promo_codes` | `GET /promo_codes` | |
> | `GET /promo_codes/{id}` | `GET /promo_codes/{id}` | |
> | `POST /promo_codes` | `POST /promo_codes` | |
> | `POST /promo_codes/{id}` | `POST /promo_codes/{id}/activate`, `POST /promo_codes/{id}/deactivate` | `status`만 다룹니다. 변형, 재고, 메타데이터를 변경하려면 새 프로모션 코드를 생성하세요. 그런 다음 이전 코드를 비활성화하세요. |
> | `DELETE /promo_codes/{id}` | `DELETE /promo_codes/{id}` | |
>
> #### 계정, 경험, 리뷰, 웹훅
>
> | v2 경로 | Current API | 참고 |
> | - | - | - |
> | `GET /company` | `GET /accounts/me` | |
> | `GET /experiences` | `GET /experiences` | |
> | `GET /experiences/{id}` | `GET /experiences/{id}` | |
> | `POST /experiences/{id}` | `PATCH /experiences/{id}` | |
> | `DELETE /experiences/{id}` | `DELETE /experiences/{id}` | |
> | `GET /reviews` | `GET /reviews` | |
> | `GET /reviews/{id}` | `GET /reviews/{id}` | |
> | `GET /webhooks` | `GET /webhooks` | |
> | `GET /webhooks/{id}` | `GET /webhooks/{id}` | |
> | `POST /webhooks` | `POST /webhooks` | [웹훅](#webhooks)을 참고하세요. |
> | `POST /webhooks/{id}` | `PATCH /webhooks/{id}` | |
> | `DELETE /webhooks/{id}` | `DELETE /webhooks/{id}` | |
>
> ### v2에서 변경된 사항
>
> #### 부분 업데이트
>
> v2는 `POST /resource/{id}`로 리소스를 업데이트했습니다. Current API는 `PATCH /resource/{id}`를 사용하며 전송한 필드만 변경합니다.
>
> #### 라이선스 키
>
> v2의 `validate_license`는 한 번의 호출로 키를 확인하고 기기에 연결했습니다. Current API에서는 서버가 라이선스 키로 멤버십을 조회하고, `status`를 확인하며, 누군가 키를 처음 사용할 때 하드웨어 ID를 `metadata`에 기록합니다. [SaaS 가이드](https://docs.whop.com/ko/supported-business-models/saas.md#license-key-integration)에 전체 예시가 있습니다.
>
> 이 호출은 서버에서 수행하세요. 계정 API 키는 비즈니스의 모든 멤버십을 변경할 수 있으므로 다운로드 가능한 소프트웨어에 절대 포함하지 마세요.
>
> #### v2 형식의 웹훅
>
> v2를 통해 생성된 웹훅은 계속 v2 형식의 페이로드를 전송합니다. 현재 형식을 받으려면 대시보드에서 또는 `POST /webhooks`로 새 웹훅을 생성하고, 핸들러를 새 웹훅으로 옮긴 다음 v2 웹훅을 삭제하세요. [웹훅](https://docs.whop.com/ko/developer/guides/webhooks.md)에서 서명 확인과 이벤트 유형을 다룹니다.

> [tab] 공개 GraphQL
>
> ### GraphQL 호출 찾기
>
> 앱이 `@whop/api`에서 `WhopServerSdk` 또는 `makeWhopServerSdk`를 가져온다면 GraphQL API를 호출하는 것입니다. `whopSdk.access.checkIfUserHasAccessToExperience` 같은 해당 클라이언트의 모든 메서드는 같은 이름의 GraphQL 작업을 전송합니다.
>
> 모든 GraphQL 응답에도 다음 헤더가 포함됩니다:
>
> | 헤더 | 예시 | 의미 |
> | - | - | - |
> | `Deprecation` | `@1789948800` | Whop이 이 API를 지원 중단했습니다. 값은 Unix 초 단위의 지원 중단 날짜입니다. |
> | `Sunset` | `Mon, 26 Oct 2026 00:00:00 GMT` | GraphQL API는 2026년 10월 26일에 작동을 중단합니다. |
> | `Link` | `<https://docs.whop.com/developer/api/migrate-from-previous-versions#public-graphql>; rel="deprecation"` | 이 가이드입니다. |
>
> 코드에서 `@whop/api`를 검색하거나 `Deprecation`이 포함된 응답을 기록하여 앱에서 아직 수행하는 모든 호출을 찾으세요.
>
> > [!NOTE]
> >
> > `@whop/api`의 `verifyUserToken`은 `x-whop-user-token` 헤더를 로컬에서 확인하며 GraphQL API를 호출하지 않으므로, 종료 이후에도 계속 작동합니다. [인증](https://docs.whop.com/ko/developer/guides/authentication.md)에서 다른 언어로 토큰을 확인하는 방법을 다룹니다.
>
> ### 작업 매핑
>
> #### 액세스 확인
>
> 대부분의 앱은 페이지를 로드할 때마다 이 중 하나를 호출합니다. 세 가지 모두 사용자 ID와 경험, 상품 또는 계정 ID를 받는 하나의 엔드포인트에 매핑됩니다.
>
> | GraphQL 작업 | Current API | 참고 |
> | - | - | - |
> | `checkIfUserHasAccessToExperience` | `GET /users/{id}/access/{resource_id}` | `resource_id`로 `exp_` ID를 전달하세요. |
> | `checkIfUserHasAccessToAccessPass` | `GET /users/{id}/access/{resource_id}` | `prod_` ID를 전달하세요. 액세스 패스는 이제 상품이라고 부릅니다. |
> | `checkIfUserHasAccessToCompany` | `GET /users/{id}/access/{resource_id}` | `biz_` ID를 전달하세요. |
>
> 응답에는 `has_access`와 `access_level`이 있으며, `access_level`은 GraphQL의 `hasAccess` 및 `accessLevel`과 같은 값인 `customer`, `admin`, `no_access` 중 하나입니다.
>
> #### 채팅 및 메시지
>
> | GraphQL 작업 | Current API | 참고 |
> | - | - | - |
> | `listMessagesFromChat` | `GET /messages` | 채팅 경험 ID를 `channel_id`로 전달하세요. [채팅 폴링 중단하기](#stop-polling-chat)를 참고하세요. |
> | `sendMessageToChat` | `POST /messages` | 채팅 경험 ID를 `channel_id`로, 텍스트를 `content`로 전달하세요. |
> | `sendDirectMessageToUser` | `POST /channels`, 그다음 `POST /messages` | `kind`를 `private`로 설정하고 `participant_user_ids`에 수신자를 넣어 대화를 생성한 다음, 해당 ID를 `channel_id`로 하여 전송하세요. |
> | `listDirectMessageConversations` | `GET /channels` | `kind=private`를 전달하세요. |
>
> #### 사용자
>
> | GraphQL 작업 | Current API | 참고 |
> | - | - | - |
> | `getUser` | `GET /users/{id}` | |
> | `getCurrentUser` | `GET /users/me` | 토큰이 속한 사용자를 반환합니다. 앱 API 키를 사용하는 경우 `verifyUserToken`에서 사용자 ID를 읽고 `GET /users/{id}`를 호출하세요. |
> | `listUsersForExperience` | `GET /members` | `product_ids`로 필터링하세요. |
>
> #### 경험 및 상품
>
> | GraphQL 작업 | Current API | 참고 |
> | - | - | - |
> | `getExperience` | `GET /experiences/{id}` | |
> | `listExperiences` | `GET /experiences` | `product_id` 또는 `app_id`로 필터링하세요. |
> | `getAccessPass` | `GET /products/{id}` | |
> | `listAccessPasses` | `GET /products` | |
> | `listAccessPassesForExperience` | `GET /products` | |
> | `createAccessPass` | `POST /products` | |
> | `updateAccessPass` | `PATCH /products/{id}` | |
> | `deleteAccessPass` | `DELETE /products/{id}` | |
> | `listPlans` | `GET /variants` | 플랜은 이제 변형이라고 부릅니다. 변형 ID는 `plan_` 접두사를 유지합니다. |
>
> #### 내 계정
>
> | GraphQL 작업 | Current API | 참고 |
> | - | - | - |
> | `getCompany` | `GET /accounts/me` | 회사는 이제 계정이라고 부릅니다. |
> | `listMemberships` | `GET /memberships` | |
> | `listMembers`, `getMember` | `GET /members`, `GET /members/{id}` | |
> | `listAuthorizedUsers` | `GET /authorized_users` | |
> | `listWaitlistEntries` | `GET /waitlist_entries` | |
> | `listReceiptsForCompany` | `GET /payments` | |
>
> #### 결제
>
> | GraphQL 작업 | Current API | 참고 |
> | - | - | - |
> | `chargeUser` | `POST /payments` | |
> | `createCheckoutSession` | `POST /checkout_configurations` | 체크아웃 세션은 이제 체크아웃 구성이라고 부릅니다. 응답에 `purchase_url`이 포함됩니다. |
> | `payUser` | `POST /transfers` | |
> | `listInvoices`, `getInvoice`, `createInvoice` | `GET /invoices`, `GET /invoices/{id}`, `POST /invoices` | |
> | `listPromoCodes`, `createPromoCode` | `GET /promo_codes`, `POST /promo_codes` | |
> | `listAffiliates`, `createAffiliate` | `GET /affiliates`, `POST /affiliates` | |
>
> #### 파일 및 알림
>
> | GraphQL 작업 | Current API | 참고 |
> | - | - | - |
> | `uploadMedia`, `processAttachment` | `POST /files`, 그다음 `POST /files/{id}/complete` | |
> | `getAttachment` | `GET /files/{id}` | |
> | `sendPushNotification` | `POST /notifications` | `experience_id` 또는 `user_ids` 목록을 대상으로 지정하세요. |
>
> #### 강좌 및 포럼
>
> | GraphQL 작업 | Current API | 참고 |
> | - | - | - |
> | `listCoursesForExperience` | `GET /courses` | `experience_id`로 필터링하세요. |
> | `listCoursesForCompany` | `GET /courses` | `account_id`로 필터링하세요. |
> | `getCourse` | `GET /courses/{id}` | |
> | `getLesson` | `GET /course_lessons/{id}` | |
> | `getUserLessonInteractions` | `GET /course_lesson_interactions` | `user_id`, `lesson_id` 또는 `course_id`로 필터링하세요. |
> | `markLessonAsCompleted` | `POST /course_lessons/{lesson_id}/mark_as_completed` | |
> | `listForumPostsFromForum` | `GET /forum_posts` | `experience_id`로 필터링하세요. |
> | `createForumPost` | `POST /forum_posts` | |
>
> #### 웹훅 작업
>
> | GraphQL 작업 | Current API | 참고 |
> | - | - | - |
> | `listWebhooks`, `getWebhook` | `GET /webhooks`, `GET /webhooks/{id}` | |
> | `createWebhook` | `POST /webhooks` | |
> | `updateWebhook` | `PATCH /webhooks/{id}` | |
> | `deleteWebhook` | `DELETE /webhooks/{id}` | |
> | `testWebhook` | `POST /webhooks/{id}/test` | |
>
> 앱에서 사용하는 작업이 목록에 없다면 [API 레퍼런스](https://docs.whop.com/ko/api-reference.md)에서 해당 리소스를 검색하거나, 작업 이름과 함께 지원팀에 문의하세요.
>
> ### 동작 변경 사항
>
> #### 채팅 폴링 중단하기
>
> 채팅 메시지에 반응하는 앱은 타이머로 `listMessagesFromChat`을 호출하는 경우가 많았습니다. 대신 `chat.message.created` 웹훅을 구독하세요. Whop은 새 메시지가 게시될 때마다 서버로 전송하므로 폴링할 필요가 없습니다. `GET /messages`는 기록을 불러올 때만 사용하세요.
>
> #### 필드 이름
>
> GraphQL은 `camelCase`(`hasAccess`, `accessLevel`)를 사용했지만 Current API 필드는 `snake_case`(`has_access`, `access_level`)를 사용합니다. 리소스 ID는 접두사를 유지하므로 저장한 ID는 계속 작동합니다.

## 페이지네이션

v2는 `page`와 `per`로 페이지를 나누고 `pagination.current_page`와 `pagination.total_page`를 반환했습니다. Current API 목록은 `data` 배열과 `page_info` 객체를 반환합니다. 페이지 크기를 설정하려면 `first`를 전달하고, 다음 페이지를 가져오려면 이전 `page_info.end_cursor`와 함께 `after`를 전달하세요. `page_info.has_next_page`가 `false`이면 중단하세요. SDK는 페이지 처리를 자동으로 해줍니다.

```typescript TypeScript theme={null}
for await (const membership of client.memberships.list({ product_id: "prod_xxxxxxxxxxxxx" })) {
  console.log(membership.id);
}
```

```python Python theme={null}
for membership in client.memberships.list(product_id="prod_xxxxxxxxxxxxx"):
    print(membership.id)
```

## 다음 단계

> [card] [API 버전](https://docs.whop.com/ko/developer/api/versioning.md)
>
> 버전을 고정하여 이후 변경 사항이 연동을 손상시키지 않도록 하세요.

> [card] [웹훅](https://docs.whop.com/ko/developer/guides/webhooks.md)
>
> 서명을 확인하고, 현재 이벤트 형식을 처리하며, 폴링 대신 채팅 메시지를 수신하세요.

> [card] [멤버십 관리](https://docs.whop.com/ko/developer/guides/memberships.md)
>
> 멤버십을 취소, 일시 중지, 연장, 업데이트하세요.

> [card] [앱 뷰](https://docs.whop.com/ko/developer/guides/app-views.md)
>
> 경험 및 대시보드 뷰에서 멤버 액세스를 확인하세요.


## Related topics

- [레거시 인보이스에서 마이그레이션하기](https://docs.whop.com/ko/developer/guides/migrate-from-legacy-invoices.md)
- [Whop API 개요](https://docs.whop.com/ko/api-reference/overview.md)
- [API 버전](https://docs.whop.com/ko/developer/api/versioning.md)
