> ## 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.

# Whop API 핵심 개념

> Whop API를 구성하는 객체: 각 객체가 무엇인지, 무엇이라고 부르는지, 어떻게 연결되는지 알아보세요.

Whop API는 예측 가능한 방식으로 연결되는 소수의 객체로 이루어져 있습니다. 이 페이지는 각 객체를 정의하며, 하나의 객체가 둘 이상의 이름으로 불리는 경우 이를 명확히 밝힙니다.

```mermaid theme={null}
graph LR
  A[계정<br/>biz_] --> P[상품<br/>prod_]
  A --> K[API 키]
  P --> L[변형<br/>plan_]
  P --> E[경험<br/>exp_]
  U[사용자<br/>user_] --> M[멤버십<br/>mem_]
  M --> P
  PAY[결제<br/>pay_] --> LG[원장<br/>ldgr_]
  LG --> PO[지급]
  LG --> T[이체]
```

## 계정 및 신원

**account** `biz_`

Whop의 비즈니스입니다. API 키, 상품, 웹훅, 자금을 소유합니다. [계정](https://docs.whop.com/ko/api-reference/accounts/account)을 참고하세요.

**user** `user_`

Whop 로그인이 있는 사람입니다. 사용자는 여러 계정에서 구매할 수 있으며, 계정 운영을 도울 수도 있습니다. [사용자](https://docs.whop.com/ko/api-reference/users/user)를 참고하세요.

**team member**

계정을 운영할 수 있는 액세스 권한을 부여받은 사용자입니다. 역할에 따라 할 수 있는 일이 결정됩니다. [팀 멤버](https://docs.whop.com/ko/api-reference/team-members/team-member)를 참고하세요.

**member**

고객으로서의 사용자입니다: 계정이 판매하는 무언가에 대한 멤버십을 보유하고 있거나 보유했던 사람입니다. [멤버](https://docs.whop.com/ko/api-reference/members/member)를 참고하세요.

### 하위 계정

마켓플레이스를 운영할 때 등록하고 대신 활동하는 계정입니다. 해당 계정을 대신하여 결제를 받고 지급합니다. 플랫폼 가이드에서는 이를 하위 판매자(sub-merchant)라고 부르기도 합니다. 두 용어는 같은 객체를 의미합니다. [플랫폼 빠른 시작](https://docs.whop.com/ko/developer/platforms/quickstart.md)에서 전체 흐름을 안내합니다.

**verification**

계정이 지급을 받기 전에 통과해야 하는 신원 확인입니다. 개인은 고객 확인(KYC) 절차를 완료합니다. 비즈니스는 기업 확인(KYB) 절차를 완료합니다. [인증](https://docs.whop.com/ko/api-reference/verifications/verification)을 참고하세요.

**identity profile** `idpf_`

인증으로 생성된 확인된 신원 데이터의 기록입니다.

## 판매하는 것

계정은 상품을 판매합니다. 상품은 가격을 설정하는 하나 이상의 변형을 가지며, 구매자가 실제로 받는 경험과 연결됩니다.

**product** `prod_`

계정이 판매하는 것입니다. 설명, 미디어, 구매자가 선택할 수 있는 변형을 보유합니다. [상품](https://docs.whop.com/ko/api-reference/products/product)을 참고하세요.

**variant** `plan_`

자체 가격, 청구 형태, 재고, SKU, 속성을 가진 상품의 구매 가능한 구성 하나입니다. 변형 ID는 `plan_` 접두사를 유지합니다. [변형](https://docs.whop.com/ko/api-reference/variants/variant)을 참고하세요.

**membership** `mem_`

구매자가 결제하면 받는 것입니다. 사용자를 변형에 연결하며, 지금 액세스가 유효한지 알려주는 상태를 포함합니다. [멤버십](https://docs.whop.com/ko/api-reference/memberships/membership)을 참고하세요.

### 경험

계정이 판매하는 것 안에 있는 콘텐츠 또는 기능 단위입니다. 상품은 하나 이상의 경험에 연결되며, 해당 상품의 멤버십이 경험에 대한 액세스를 부여합니다.

이는 Whop에서 가장 플랫폼 고유한 명사이며, 이름만으로는 짐작할 수 없는 용어입니다. Whop 안에서 실행되는 앱을 빌드한다면, 경험은 앱이 렌더링되는 대상입니다. [앱 뷰](https://docs.whop.com/ko/developer/guides/app-views.md)를 참고하세요.

### 권한 부여

사용자가 지금 특정 항목을 사용할 수 있다는 기록입니다. 액세스는 질문이고, 권한 부여(entitlement)는 저장된 답입니다. 계정, 상품 또는 경험에 대해 확인하세요. [인증](https://docs.whop.com/ko/developer/guides/authentication.md)을 참고하세요.

## 자금 이동 방식

자금은 들어와서 어딘가에 머문 다음 나갑니다. 아래의 각 객체는 그 경로의 한 단계이며, 발생 순서대로 나열되어 있습니다.

**checkout configuration** `ch_`

구매에 대한 재사용 가능한 정의입니다: 어떤 변형을, 어떤 가격에, 어떤 리디렉션으로. 라이브 결제 페이지를 생성합니다. [체크아웃 구성](https://docs.whop.com/ko/api-reference/checkout-configurations/checkout-configuration)을 참고하세요.

**payment** `pay_`

구매자에서 계정으로 자금을 이동하려는 한 번의 시도로, 성공 여부를 알려주는 상태를 포함합니다.

**charge**

카드 네트워크 측에서 설명한 동일한 이벤트입니다. 문서에서는 두 용어를 모두 사용합니다. API 객체는 payment입니다.

### 원장

계정 자금의 모든 입금과 출금에 대한 누적 기록입니다. 계정이 보유한 것과 받을 것에 대한 신뢰할 수 있는 원천입니다. 자금은 다른 곳으로 가기 전에 먼저 원장에 들어옵니다. [원장 활동](https://docs.whop.com/ko/api-reference/ledgers/ledger-activity)을 참고하세요.

**balance**

지금 원장에 있으며 사용하거나 출금할 수 있는 금액입니다.

**reserve**

향후 환불 및 분쟁에 대비하여 Whop이 보류하는 잔액의 일부입니다. 일정에 따라 해제됩니다.

**fee**

자금이 잔액에 도달하기 전에 공제되는 결제에 대한 Whop의 몫입니다.

**deposit**

Whop 외부에서 잔액에 추가된 자금입니다. [입금](https://docs.whop.com/ko/api-reference/deposits/deposit)을 참고하세요.

**payout**

잔액에서 Whop 외부의 은행 계좌나 지갑으로 나가는 자금입니다. [지급](https://docs.whop.com/ko/api-reference/payouts/payout)을 참고하세요.

**transfer**

외부를 거치지 않고 Whop 내부의 두 계정 간에 이동하는 자금입니다. [이체](https://docs.whop.com/ko/api-reference/transfers/transfer)를 참고하세요.

**swap**

지원되는 토큰, 체인 또는 지갑 대상 간의 잔액 전환입니다. [스왑](https://docs.whop.com/ko/api-reference/swaps/swap)을 참고하세요.

**card** `icrd_`

계정 또는 사용자 잔액에서 지출하는 Whop 발급 가상 카드입니다. [카드](https://docs.whop.com/ko/api-reference/cards/card)를 참고하세요.

**refund**

사용자가 시작하여 구매자에게 반환된 완료된 결제입니다.

**dispute**

구매자의 은행이 구매자를 대신하여 되돌린 결제입니다. 이의를 제기할 수 있습니다. [분쟁](https://docs.whop.com/ko/api-reference/disputes/dispute)을 참고하세요.

## Whop에서 빌드하기

> [!NOTE]
>
> 이 문서에서 **플랫폼**은 두 가지를 의미합니다. 플랫폼으로서의 Whop은 연동하는 대상 제품입니다. 마켓플레이스 의미의 플랫폼은 하위 계정을 등록하고 그 판매액의 일부를 받는 *여러분*입니다. 주변 문장을 보면 어느 쪽을 의미하는지 알 수 있습니다.

**app** `app_`

Whop 안에서 실행되며 마켓플레이스를 통해 사용자에게 도달하는 소프트웨어입니다. [앱](https://docs.whop.com/ko/api-reference/apps/app)을 참고하세요.

**app view**

앱이 Whop 안에서 렌더링하는 하나의 화면입니다: 고객용 경험 뷰 또는 크리에이터용 대시보드 뷰. [앱 뷰](https://docs.whop.com/ko/developer/guides/app-views.md)를 참고하세요.

**iframe**

Whop이 자체 인터페이스에 앱 페이지를 임베드하는 방식입니다. 앱은 여러분의 서버에서 실행되며 Whop의 UI 프레임 안에서 렌더링됩니다. [iframe](https://docs.whop.com/ko/developer/guides/iframe.md)을 참고하세요.

**permission**

API 키가 행사할 수 있는 단일 기능입니다. [권한](https://docs.whop.com/ko/developer/guides/permissions.md)을 참고하세요.

### 스코프

권한과 같은 개념이지만 OAuth 토큰에 적용됩니다: 사용자가 앱이 자신을 대신하여 할 수 있도록 동의한 항목의 집합입니다. 권한은 키가 할 수 있는 것입니다. 스코프는 사용자가 허락한 것입니다. [OAuth 가이드](https://docs.whop.com/ko/developer/guides/oauth.md)를 참고하세요.

**OAuth grant**

사용자가 일련의 스코프에 대해 앱을 승인한 기록입니다.

**element**

Whop이 제공하는 사전 빌드된 UI 컴포넌트로, 자체 제품에 넣기만 하면 되므로 인터페이스를 직접 빌드할 필요가 없습니다.

**event**

결제 성공처럼 계정에서 발생한 일입니다.

**webhook**

이벤트가 발생했음을 알리기 위해 Whop이 서버로 보내는 HTTP 요청입니다. [웹훅](https://docs.whop.com/ko/developer/guides/webhooks.md)을 참고하세요.

## 커뮤니티

**chat channel**

멤버들이 서로 메시지를 보내는 공간입니다. [채팅](https://docs.whop.com/ko/developer/guides/chat/quickstart.md)을 참고하세요.

**message**

채팅 채널 또는 다이렉트 메시지의 게시물 하나입니다.

**forum**

실시간 채팅과 별개로 더 긴 게시물을 위한 스레드형 공간입니다. [포럼](https://docs.whop.com/ko/developer/guides/forums.md)을 참고하세요.

**forum post**

답글과 반응을 포함하는 포럼의 스레드 하나입니다.

**notification**

Whop 안에서 사용자에게 푸시되는 메시지입니다. 각 전송은 하나의 경험 또는 한 명의 사용자를 대상으로 합니다. [알림](https://docs.whop.com/ko/developer/guides/notifications.md)을 참고하세요.

## 광고

**ad campaign** `adcamp_`

광고 네트워크의 유료 광고를 위한 최상위 컨테이너입니다. 플랫폼, 목표, 예산 전략을 설정합니다. [광고 캠페인](https://docs.whop.com/ko/api-reference/ad-campaigns/ad-campaign)을 참고하세요.

**ad group** `adgrp_`

캠페인 안에 있으며 게재를 제어합니다: 타기팅, 최적화 목표, 일정. [광고 그룹](https://docs.whop.com/ko/api-reference/ad-groups/ad-group)을 참고하세요.

**ad** `ad_`

광고 그룹이 게재하는 크리에이티브 단위입니다: 문구, 에셋, 목적지 URL. [광고](https://docs.whop.com/ko/api-reference/ads/ad)를 참고하세요.

**audience**

Whop에 업로드되어 광고 그룹에서 사람을 타기팅하거나 제외하는 데 사용되는 고객 목록입니다. [오디언스](https://docs.whop.com/ko/api-reference/audiences/audience)를 참고하세요.

## 추천 및 보상

**affiliate** `aff_`

상품에 구매자를 보내 커미션을 받는 사람입니다. [제휴](https://docs.whop.com/ko/developer/guides/affiliates.md)를 참고하세요.

**partner**

Whop 파트너 프로그램에 등록되어 Whop에 추천한 비즈니스로 수익을 얻는 사용자입니다. [파트너](https://docs.whop.com/ko/developer/partners/overview.md)를 참고하세요.

**referred business** `coma_`

파트너가 Whop에 데려온 비즈니스로, 적용되는 커미션 비율과 추천 기간을 포함합니다.

**partner earning**

추천된 비즈니스에 대한 커미션 항목 하나로, 발생한 수입원과 상태를 명시합니다.

**bounty** `bnty_`

게시되는 순간부터 보상이 에스크로에 보관되는 유료 작업입니다. [바운티](https://docs.whop.com/ko/developer/bounties/overview.md)를 참고하세요.

**bounty submission** `btys_`

시도부터 검토, 지급까지 이어지는 바운티에 대한 한 작업자의 시도입니다.

## 환경 및 키

Whop은 두 가지 환경을 운영합니다. 두 환경은 아무것도 공유하지 않습니다.

| | 샌드박스 | 프로덕션 |
| - | - | - |
| 자금 | 이동하지 않음 | 실제 |
| 대시보드 | 별도 | 별도 |
| 키 | 자체 세트 | 자체 세트 |
| 데이터 | 테스트 데이터 | 실제 데이터 |

전환 방법은 [샌드박스에서 테스트하기](https://docs.whop.com/ko/developer/guides/sandbox.md)를 참고하세요.

> [!WARNING]
>
> 샌드박스 키와 프로덕션 키는 똑같이 생겼습니다. 키 문자열만으로는 어느 환경에 속하는지 알 수 없으므로, 서로 다른 이름으로 저장하고 자금을 이동하는 작업을 실행하기 전에 확인하세요.

다섯 가지 자격 증명 유형으로 API에 접근할 수 있습니다. 누구의 데이터가 필요한지에 따라 선택하세요.

| 자격 증명 | 동작 주체 | 사용 시점 |
| - | - | - |
| API 키 | 내 계정 또는 내 앱 | 서버가 자체 비즈니스 또는 앱을 설치한 모든 계정에서 작업할 때 |
| 계정 범위 사용자 토큰 | 하나의 계정 안의 한 사용자 | 제품에 자체 사용자가 있고 이들이 Whop 로그인 없이 Whop에 접근할 때 |
| 계정 액세스 토큰 | 권한이 좁혀진 내 계정 | 클라이언트가 API 키를 보유하지 않고 계정에 단기 액세스해야 할 때 |
| iframe 사용자 토큰 | 앱을 보고 있는 사용자 | 앱이 Whop 안에서 렌더링되며 누가 보고 있는지 알아야 할 때 |
| OAuth 토큰 | Whop에 로그인한 사용자 | 사용자가 로그인하여 앱을 승인했을 때 |

각 자격 증명을 선택하고 범위를 지정하는 방법은 [인증 및 API 키](https://docs.whop.com/ko/developer/guides/auth-scoping.md)를 참고하세요.

**Api-Version-Date**

연동을 날짜가 지정된 API 버전에 고정하여 이후 변경 사항이 기준으로 삼은 응답을 바꾸지 않도록 하는 헤더입니다. [API 버전 관리](https://docs.whop.com/ko/developer/api/versioning.md)를 참고하세요.

**idempotency key**

`POST`에 첨부하는 값으로, 재시도할 때 작업을 두 번 수행하는 대신 원래 응답을 재생합니다. [멱등성 요청](https://docs.whop.com/ko/developer/api/idempotency.md)을 참고하세요.

## ID 레퍼런스

모든 객체에는 접두사가 붙은 ID가 있습니다. 페이로드를 보고 있을 때 이 표를 보면 무엇을 다루고 있는지 알 수 있습니다.

| 접두사 | 객체 | 참고 |
| - | - | - |
| `biz_` | 계정 | [계정](https://docs.whop.com/ko/api-reference/accounts/account) |
| `user_` | 사용자 | [사용자](https://docs.whop.com/ko/api-reference/users/user) |
| `prod_` | 상품 | [상품](https://docs.whop.com/ko/api-reference/products/product) |
| `plan_` | 변형 | [변형](https://docs.whop.com/ko/api-reference/variants/variant) |
| `mem_` | 멤버십 | [멤버십](https://docs.whop.com/ko/api-reference/memberships/membership) |
| `exp_` | 경험 | [앱 뷰](https://docs.whop.com/ko/developer/guides/app-views.md) |
| `app_` | 앱 | [앱](https://docs.whop.com/ko/api-reference/apps/app) |
| `pay_` | 결제 | [개요](https://docs.whop.com/ko/api-reference/overview.md) |
| `ch_` | 체크아웃 구성 | [체크아웃 구성](https://docs.whop.com/ko/api-reference/checkout-configurations/checkout-configuration) |
| `ldgr_` | 원장 계정 | [원장 활동](https://docs.whop.com/ko/api-reference/ledgers/ledger-activity) |
| `idpf_` | 신원 프로필 | [인증](https://docs.whop.com/ko/api-reference/verifications/verification) |
| `sacc_` | 외부 계정 | [외부 계정](https://docs.whop.com/ko/api-reference/external-accounts/external-account) |
| `aff_` | 제휴 | [제휴](https://docs.whop.com/ko/developer/guides/affiliates.md) |
| `adcamp_` | 광고 캠페인 | [광고 캠페인](https://docs.whop.com/ko/api-reference/ad-campaigns/ad-campaign) |
| `adgrp_` | 광고 그룹 | [광고 그룹](https://docs.whop.com/ko/api-reference/ad-groups/ad-group) |
| `ad_` | 광고 | [광고](https://docs.whop.com/ko/api-reference/ads/ad) |
| `bnty_` | 바운티 | [바운티](https://docs.whop.com/ko/developer/bounties/overview.md) |
| `btys_` | 바운티 제출물 | [바운티](https://docs.whop.com/ko/developer/bounties/overview.md) |
| `coma_` | 추천된 비즈니스 | [파트너](https://docs.whop.com/ko/developer/partners/overview.md) |
| `icrd_` | 카드 | [카드](https://docs.whop.com/ko/api-reference/cards/card) |
| `course_` | 강좌 | [개요](https://docs.whop.com/ko/api-reference/overview.md) |
| `file_` | 파일 | [개요](https://docs.whop.com/ko/api-reference/overview.md) |

## 다음 단계

> [card] [빠른 시작](https://docs.whop.com/ko/developer/quickstart.md)
>
> 몇 분 안에 첫 API 호출을 해보세요.

> [card] [샌드박스에서 테스트하기](https://docs.whop.com/ko/developer/guides/sandbox.md)
>
> 실제 서비스 전에 테스트 데이터로 모든 것을 시도해 보세요.

> [card] [API 개요](https://docs.whop.com/ko/api-reference/overview.md)
>
> 요청, 버전 관리, 페이지네이션의 작동 방식.

> [card] [만들 수 있는 것](https://docs.whop.com/ko/developer/start.md)
>
> 전체 기능 맵과 빌드하려는 것에 대한 가이드.


## Related topics

- [Whop Partners API](https://docs.whop.com/ko/developer/partners/overview.md)
- [Whop API 개요](https://docs.whop.com/ko/api-reference/overview.md)
- [Whop 앱 빌드하기](https://docs.whop.com/ko/developer/apps/overview.md)
