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

# SaaS

> Whop에서 소프트웨어를 판매하세요. 각 사용자의 접근 권한을 확인하여 웹 앱을 보호하거나, 라이선스 키로 다운로드형 소프트웨어를 보호하세요.

Whop은 소프트웨어의 체크아웃, 청구, 구독 관리를 처리합니다. 앱은 누군가를 들여보내기 전에 해당 고객이 현재 접근 권한을 가지고 있는지 Whop에 확인합니다. 이 페이지에서는 이 확인을 수행하는 두 가지 방법을 보여 줍니다.

## 통합 방식 선택하기

| | 접근 권한 확인 | 라이선스 키 |
| - | - | - |
| **적합한 용도** | 사용자가 사이트에 로그인하는 웹 앱 | 사용자가 다운로드하는 데스크톱 앱, 스크립트, 도구 |
| **고객 식별 방법** | 사용자 레코드에 저장된 Whop 사용자 ID | 구매할 때마다 Whop이 발급하는 라이선스 키 |
| **서버에서 호출하는 항목** | `users.checkAccess` | `memberships.retrieve` 및 `memberships.update` |
| **한 대의 기기로 제한** | 아니요 | 예, 멤버십 메타데이터의 하드웨어 ID 사용 |

두 방식 모두 동일한 설정을 공유합니다.

## 설정

### 1. whop과 상품 만들기

[whop.com/sell](https://whop.com/dashboard/start/)에서 시작하여 whop의 이름을 정하고 URL을 선택하세요. 그런 다음 대시보드의 **Products**로 이동하여 고객이 지불할 가격으로 상품을 추가하세요. 상품 ID(`prod_`)와 플랜 ID(`plan_`)를 복사하세요. 아래에서 둘 다 필요합니다.

### 2. API 키 만들기

대시보드에서 **Developer → API keys**로 이동하여 계정 API 키를 만드세요. 이 키는 비즈니스를 대신하여 작동하므로 서버에 보관하고, 클라이언트 코드나 다운로드형 앱에 절대 포함하지 마세요. `WHOP_API_KEY`로 저장하세요.

### 3. SDK 설치하기

```bash npm theme={null}
npm install @whop/sdk
```

```bash pip theme={null}
pip install whop-sdk
```

클라이언트를 하나 만들어 재사용하세요. 이 페이지의 예제에서는 이를 `client`라고 부릅니다.

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

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

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

from whop_sdk import Whop

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

## 이메일 로그인 통합

고객이 자체 웹 앱에 로그인할 때 이 방식을 사용하세요. 각 고객의 Whop 사용자 ID를 사용자 레코드에 저장한 다음, 유료 기능을 제공하기 전에 이를 사용해 접근 권한을 확인하세요.

### 1. 사용자 테이블에 Whop 열 추가하기

| 열 | 타입 | 설명 |
| - | - | - |
| `whop_user_id` | string | `user_` 접두사가 붙은 고객의 Whop 사용자 ID입니다. |
| `whop_username` | string | 선택 사항입니다. 고객의 Whop 사용자 이름입니다. UI와 로그에 표시하세요. |

### 2. 로그인한 사용자를 체크아웃으로 보내기

서버에서 체크아웃 구성을 만들고 자체 사용자 ID를 `metadata`에 넣으세요. Whop은 이 메타데이터를 멤버십에 복사하며, 다음 단계에서 이를 통해 구매를 사용자와 연결합니다. 그런 다음 사용자를 `purchase_url`로 리디렉션하세요.

```typescript TypeScript theme={null}
export async function startCheckout(userId: string) {
  const checkout = await client.checkoutConfigurations.create({
    variant_id: process.env.WHOP_VARIANT_ID!,
    metadata: { customer_id: userId },
    redirect_url: "https://yourapp.com/billing/return",
  });

  return checkout.purchase_url;
}
```

```python Python theme={null}
def start_checkout(user_id: str) -> str:
    checkout = client.checkout_configurations.create(
        variant_id=os.environ["WHOP_VARIANT_ID"],
        metadata={"customer_id": user_id},
        redirect_url="https://yourapp.com/billing/return",
    )

    return checkout.purchase_url
```

구매자를 자체 페이지에 머물게 하려면 [Checkout 요소를 임베드](https://docs.whop.com/ko/developer/guides/embed-checkout.md)하고 핸들에 동일한 `metadata`를 전달하세요. [결제 받기](https://docs.whop.com/ko/developer/guides/accept-payments.md)에서 모든 체크아웃 옵션을 비교합니다.

### 3. 웹훅에서 Whop 사용자 ID 저장하기

[대시보드의 Developer 탭](https://whop.com/dashboard/developer)을 열고 **Create webhook**을 선택한 다음, `membership.activated`를 구독하고 서명 시크릿을 `WHOP_WEBHOOK_SECRET`으로 저장하세요. 이벤트의 `data`는 구매자의 `user_id`와 체크아웃에서 설정한 `metadata`가 포함된 멤버십입니다.

```typescript TypeScript theme={null}
// app/api/webhooks/whop/route.ts
import { unwrapWebhook } from "@whop/sdk/helpers";
import type { NextRequest } from "next/server";

export async function POST(request: NextRequest) {
  // Verify the raw body. Parsing it first changes the bytes and the signature check fails.
  const event = unwrapWebhook(await request.text(), {
    headers: Object.fromEntries(request.headers),
    key: process.env.WHOP_WEBHOOK_SECRET!,
  });

  if (event.type === "membership.activated") {
    const customerId = event.data.metadata?.customer_id;
    if (customerId && event.data.user_id) {
      await db.users.update(customerId, { whop_user_id: event.data.user_id });
    }
  }

  return new Response("OK", { status: 200 });
}
```

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

from fastapi import FastAPI, Request, Response
from whop_sdk.lib.verify_webhook import unwrap

app = FastAPI()


@app.post("/api/webhooks/whop")
async def whop_webhook(request: Request):
    # Verify the raw body. Parsing it first changes the bytes and the signature check fails.
    event = unwrap(await request.body(), dict(request.headers), os.environ["WHOP_WEBHOOK_SECRET"])

    if event["type"] == "membership.activated":
        membership = event["data"]
        customer_id = (membership.get("metadata") or {}).get("customer_id")
        if customer_id and membership.get("user_id"):
            db.users.update(customer_id, whop_user_id=membership["user_id"])

    return Response(status_code=200)
```

`membership.activated`는 갱신 시에도 발생하므로, 반복해도 안전하도록 쓰기 작업을 구성하세요. 재시도와 테스트는 [웹훅](https://docs.whop.com/ko/developer/guides/webhooks.md)에서 다룹니다.

### 4. 유료 기능 제공 전에 접근 권한 확인하기

사용자가 상품에 접근 권한이 있는지 Whop에 물어보세요. 응답은 갱신, 취소, 환불을 반영하므로 청구 상태를 직접 추적할 필요가 없습니다.

```typescript TypeScript theme={null}
export async function hasAccess(whopUserId: string) {
  const access = await client.users.checkAccess({
    id: whopUserId,
    resource_id: process.env.WHOP_PRODUCT_ID!,
  });

  return access.has_access;
}
```

```python Python theme={null}
def has_access(whop_user_id: str) -> bool:
    access = client.users.check_access(
        resource_id=os.environ["WHOP_PRODUCT_ID"],
        id=whop_user_id,
    )

    return access.has_access
```

같은 응답의 `access_level`은 `customer`, `admin`, `no_access` 중 하나입니다.

### 5. 고객이 청구를 관리할 수 있게 하기

고객이 결제 수단을 업데이트하거나 취소할 수 있도록 [Whop 주문](https://whop.com/@me/settings/orders) 링크를 제공하세요. 고객은 구매 시 사용한 이메일로 로그인합니다.

## 라이선스 키 통합

고객의 기기에서 실행되는 소프트웨어에는 이 방식을 사용하세요. 구매할 때마다 고유한 라이선스 키가 제공됩니다. 소프트웨어가 키를 요청하고, 서버가 Whop으로 키를 확인합니다.

### 1. 상품에 Software 앱 추가하기

whop에 [Software 앱을 설치](https://whop.com/apps/app_jHH5YT7jHYQANi/install/)하고, 앱을 열어 소프트웨어 이름과 다운로드 링크를 추가하세요. 그러면 구매자는 주문 내역에서 라이선스 키와 다운로드를 확인할 수 있습니다. API는 상품에 이 앱이 포함된 경우에만 멤버십의 `license_key`를 반환합니다.

### 2. 서버에서 키 검증하기

배포하는 소프트웨어가 아니라 자체 서버에서 키를 확인하세요. API 키는 비즈니스의 모든 멤버십을 읽고 변경할 수 있으므로, 사용자가 다운로드하는 데스크톱 앱이나 스크립트에 절대 포함하지 마세요. 소프트웨어는 라이선스 키와 기기 식별자를 서버로 전송하고, 서버는 Whop으로 이를 확인합니다.

각 키를 한 대의 기기로 제한하려면, 누군가 키를 처음 사용할 때 멤버십의 메타데이터에 하드웨어 ID를 저장한 다음 이후 확인할 때마다 비교하세요:

* **키가 아직 연결되지 않은 경우**(메타데이터에 `hwid`가 없음): 기기의 `hwid`를 저장하고 접근을 허용합니다.
* **저장된 `hwid`가 일치하는 경우:** 접근을 허용합니다.
* **저장된 `hwid`가 다른 경우:** 접근을 거부합니다. 고객이 재설정할 때까지 키는 다른 기기에서 사용 중입니다.

```typescript TypeScript theme={null}
// Add "past_due" if you let customers keep access while Whop retries a failed renewal.
const VALID_STATUSES = ["active", "trialing", "completed"];

export async function validateLicense(licenseKey: string, hwid: string) {
  // Retrieve accepts a license key in place of a membership ID. An unknown key throws a 404 error.
  const membership = await client.memberships.retrieve({ id: licenseKey });

  if (!VALID_STATUSES.includes(membership.status)) {
    return { valid: false, reason: "membership_inactive" };
  }

  const boundHwid = membership.metadata?.hwid;

  if (!boundHwid) {
    // Update merges these keys into the existing metadata.
    await client.memberships.update({ id: membership.id, metadata: { hwid } });
    return { valid: true };
  }

  if (boundHwid !== hwid) {
    return { valid: false, reason: "bound_to_another_machine" };
  }

  return { valid: true };
}
```

```python Python theme={null}
# Add "past_due" if you let customers keep access while Whop retries a failed renewal.
VALID_STATUSES = {"active", "trialing", "completed"}


def validate_license(license_key: str, hwid: str) -> dict:
    # Retrieve accepts a license key in place of a membership ID. An unknown key raises a 404 error.
    membership = client.memberships.retrieve(license_key)

    if membership.status not in VALID_STATUSES:
        return {"valid": False, "reason": "membership_inactive"}

    bound_hwid = (membership.metadata or {}).get("hwid")

    if not bound_hwid:
        # Update merges these keys into the existing metadata.
        client.memberships.update(membership.id, metadata={"hwid": hwid})
        return {"valid": True}

    if bound_hwid != hwid:
        return {"valid": False, "reason": "bound_to_another_machine"}

    return {"valid": True}
```

### 3. 라이선스 키 재설정하기

고객은 주문 내역에서 키를 재설정할 수 있습니다. 서버에서 재설정하려면 빈 메타데이터 객체(`metadata: {}`)로 [멤버십을 업데이트](https://docs.whop.com/ko/api-reference/memberships/update-membership.md)하세요. 이후 어떤 기기에서든 다음 확인 시 키가 다시 연결됩니다.

## 스토어 페이지 디자인하기

스토어 페이지는 사람들이 구매하기 전에 소프트웨어에 대해 알아보는 곳입니다. 왼쪽 상단에서 whop 이름을 선택한 다음 **Design store page**를 선택하여 편집기를 여세요. **Edit details**를 선택하여 다음을 사용자 지정하세요:

* **이름과 헤드라인:** 소프트웨어가 무엇을 하고 누구를 위한 것인지 알려 주세요.
* **설명:** 해결하는 문제와 업데이트, 지원, 커뮤니티 등 구매자가 얻는 것에 초점을 맞추세요.
* **로고:** 깔끔하고 간단한 로고를 추가하세요.
* **갤러리 이미지 또는 동영상:** 소프트웨어가 사용되는 모습을 보여 주세요. 짧은 데모 동영상은 구매자의 결정에 도움이 됩니다.
* **카테고리:** 사람들이 Whop을 둘러볼 때 소프트웨어를 찾는 데 도움이 되는 카테고리를 선택하세요.

## 다음 단계

> [card] [결제 받기](https://docs.whop.com/ko/developer/guides/accept-payments.md)
>
> 체크아웃 링크, Checkout 요소, 결제 요소를 비교하세요.

> [card] [웹훅](https://docs.whop.com/ko/developer/guides/webhooks.md)
>
> 서명을 확인하고, 재시도를 처리하고, 이벤트를 테스트하세요.

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

> [card] [Whop으로 로그인](https://docs.whop.com/ko/developer/guides/oauth.md)
>
> 고객이 비밀번호 대신 Whop 계정으로 로그인할 수 있게 하세요.


## Related topics

- [Whop 시작하기](https://docs.whop.com/ko/get-started.md)
- [Whop 앱이란](https://docs.whop.com/ko/whop-apps/what-are-whop-apps.md)
