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

# Memberships API

> 멤버십(Membership)은 고객의 베리언트 구매로, 상품에 대한 접근 권한을 부여하는 구독 또는 일회성 권한입니다.

결제 상태(`active`, `trialing`, `past_due` 등), 현재 기간, 대기 중인 취소, 사용자 지정 메타데이터, 그리고 상품에 라이선스가 포함된 경우 소프트웨어 라이선스 키를 추적합니다.

Memberships API를 사용하여 계정의 멤버십 또는 본인의 멤버십 목록을 조회하고, ID나 라이선스 키로 단일 멤버십을 조회하고, 무료 베리언트를 통해 수신자를 초대하고, 수명 주기를 관리할 수 있습니다: 즉시 또는 기간 종료 시 취소, 예약된 취소 되돌리기, 결제 수금 일시 중지 및 재개, 접근 권한 연장 또는 재활성화, 프로모션 코드 또는 제휴자 적용, 갱신 주기 변경, 접근 권한 재동기화, 이전 링크 생성, 메타데이터 업데이트가 가능합니다.

> [!NOTE]
>
> Legacy [Memberships](https://docs.whop.com/ko/api-reference/memberships/membership) 리소스를 대체합니다. 기존 Legacy 통합은 계속 작동합니다. 안정성 보장에 대해서는 [API 버전](https://docs.whop.com/ko/developer/api/versioning.md)을 참조하세요.

## 엔드포인트

| 엔드포인트 | 요청 |
| - | - |
| [멤버십 목록 조회](https://docs.whop.com/ko/api-reference/memberships/list-memberships.md) | GET `/memberships` |
| [멤버십 조회](https://docs.whop.com/ko/api-reference/memberships/retrieve-membership.md) | GET `/memberships/{id}` |
| [멤버십에 프로모션 코드 적용](https://docs.whop.com/ko/api-reference/memberships/apply-promo-code-to-membership.md) | POST `/memberships/{id}/apply_promo_code` |
| [멤버십에 제휴자 지정](https://docs.whop.com/ko/api-reference/memberships/assign-affiliate-to-membership.md) | POST `/memberships/{id}/assign_affiliate` |
| [멤버십 취소](https://docs.whop.com/ko/api-reference/memberships/cancel-membership.md) | POST `/memberships/{id}/cancel` |
| [멤버십 연장](https://docs.whop.com/ko/api-reference/memberships/extend-membership.md) | POST `/memberships/{id}/extend` |
| [멤버십 일시 중지](https://docs.whop.com/ko/api-reference/memberships/pause-membership.md) | POST `/memberships/{id}/pause` |
| [멤버십 재활성화](https://docs.whop.com/ko/api-reference/memberships/reactivate-membership.md) | POST `/memberships/{id}/reactivate` |
| [멤버십 재개](https://docs.whop.com/ko/api-reference/memberships/resume-membership.md) | POST `/memberships/{id}/resume` |
| [멤버십 접근 권한 재동기화](https://docs.whop.com/ko/api-reference/memberships/resync-membership-access.md) | POST `/memberships/{id}/resync_access` |
| [멤버십 이전](https://docs.whop.com/ko/api-reference/memberships/transfer-membership.md) | POST `/memberships/{id}/transfer` |
| [멤버십에 초대](https://docs.whop.com/ko/api-reference/memberships/invite-to-a-membership.md) | POST `/memberships/invite` |
| [멤버십 업데이트](https://docs.whop.com/ko/api-reference/memberships/update-membership.md) | PATCH `/memberships/{id}` |

## 속성

**id** `string` *required*

멤버십 ID이며, 접두사는 `mem_`입니다.

**account** `object` *required*

이 멤버십이 속한 계정(판매자)입니다.

> [accordion] 속성
>
> **id** `string` *required*
>
> 계정 ID이며, 접두사는 `biz_`입니다.
>
> **logo\_url** `string | null` *required*
>
> 계정 로고 이미지 URL입니다. 계정이 설정하지 않은 경우 `null`입니다.
>
> **route** `string` *required*
>
> 계정의 공개 경로 식별자로, `whop.com/\{route}` 스토어프런트 경로에 사용됩니다.
>
> **title** `string` *required*
>
> 계정 표시 이름입니다.

**affiliate** `object | null` *required*

멤버십의 제휴 수수료입니다. 제휴자가 없거나, 계정에 `affiliate:basic:read` 권한이 없는 경우 `null`이며, 웹훅에서는 항상 `null`입니다.

> [accordion] 속성
>
> **id** `string` *required*
>
> 제휴자 ID이며, 접두사는 `aff_`입니다.
>
> **applies\_to\_payments** `string` *required*
>
> 수수료가 멤버십의 첫 결제에만 지급되는지 또는 모든 결제에 지급되는지 여부입니다.
>
> 사용 가능한 옵션: `first_payment`, `all_payments`
>
> **commission\_amount** `object | null` *required*
>
> 멤버십 통화로 된 정액 수수료이며, 비율 수수료인 경우 `null`입니다.
>
> > [accordion] 속성
> >
> > **amount** `string` *required*
> >
> > 주 단위 금액으로, 정확한 소수 문자열입니다. 예를 들어 `"10.00"`은 10달러입니다. 전송 중에 부동 소수점 반올림이 발생하지 않도록 문자열로 제공됩니다.
> >
> > **currency** `string` *required*
> >
> > 소문자로 된 세 자리 ISO 4217 통화 코드입니다.
> >
> > **decimals** `integer` *required*
> >
> > 금액이 가지는 소수 자릿수입니다. 청구 자체가 실행되는 정밀도입니다.
> >
> > **display\_decimals** `integer` *required*
> >
> > 표시할 소수 자릿수입니다. 일반적으로 `decimals`와 같지만 의도적으로 항상 같지는 않습니다: COP는 센타보 단위로 청구되지만 페소 단위로 표기되므로 각각 `2`와 `0`입니다. 이 값을 사용하여 자체 로캘에 맞게 숫자 형식을 지정하세요.
>
> **commission\_percentage** `number | null` *required*
>
> 퍼센트포인트 단위의 비율 수수료로, `20`은 20%를 의미하며, 정액 수수료인 경우 `null`입니다.
>
> **commission\_source** `string` *required*
>
> 수수료율이 설정된 방식: 이 제휴자에 대해 설정된 요율은 `custom`, 플랜 또는 상품의 멤버 제휴 요율은 `member`, 상품의 글로벌 제휴 요율은 `global`, Whop 마켓플레이스 추천은 `marketplace`입니다.
>
> 사용 가능한 옵션: `custom`, `member`, `marketplace`, `global`
>
> **commission\_type** `string` *required*
>
> 수수료가 비율인지 정액인지 여부입니다.
>
> 사용 가능한 옵션: `flat_fee`, `percentage`
>
> **enabled** `boolean` *required*
>
> 이 멤버십이 제휴 수수료를 지급하는지 여부입니다. `false`는 제휴자가 멤버십에 유지되지만 더 이상 수수료가 지급되지 않음을 의미합니다.
>
> **user\_id** `string` *required*
>
> 제휴자 사용자의 ID이며, 접두사는 `user_`입니다.

**billing\_period\_days** `integer | null` *required*

반복 청구 사이의 일수입니다. 갱신되지 않는 멤버십이나 여러 갱신 일정이 있는 멤버십의 경우 `null`입니다.

**cancel\_at\_period\_end** `boolean` *required*

현재 결제 기간이 끝날 때 멤버십이 취소되도록 설정되어 있는지 여부입니다. 반복 베리언트에서만 의미가 있습니다.

**cancel\_option** `string | null` *required*

멤버가 취소 사유로 선택한 카테고리입니다. 카테고리를 선택하지 않은 경우 `null`입니다.

사용 가능한 옵션: `too_expensive`, `switching`, `missing_features`, `technical_issues`, `bad_experience`, `unused`, `other`, `testing`

**canceled\_at** `string | null` *required*

취소가 요청된 시점, 또는 요청 시간이 기록되지 않은 경우 멤버십이 취소된 시점으로, ISO 8601 타임스탬프입니다. 둘 다 기록되지 않은 경우 `null`입니다.

**cancellation\_reason** `string | null` *required*

취소 시 제공된 자유 텍스트 설명입니다. 사유가 제공되지 않은 경우 `null`입니다.

**collection\_method** `string | null` *required*

갱신 금액이 수금되는 방식입니다. `charge_automatically`는 매 기간 저장된 결제 수단으로 청구하고, `send_invoice`는 매 기간 구매자에게 인보이스를 이메일로 보냅니다. 설정되지 않은 경우 `null`입니다.

사용 가능한 옵션: `charge_automatically`, `send_invoice`

**created\_at** `string` *required*

멤버십이 생성된 시점으로, ISO 8601 타임스탬프입니다.

**current\_period\_end** `string | null` *required*

현재 결제 기간이 갱신되는 시점, 또는 갱신되지 않는 멤버십이 만료되는 시점으로, ISO 8601 타임스탬프입니다. 만료가 없는 일회성 구매의 경우 `null`입니다.

**current\_period\_start** `string | null` *required*

현재 결제 기간이 시작된 시점으로, ISO 8601 타임스탬프입니다. 기록된 결제 기간이 없는 경우 `null`입니다.

**expires\_at** `string | null` *required*

고정 만료일이 있는 멤버십의 접근 권한이 종료되는 시점으로, ISO 8601 타임스탬프입니다. 갱신되는 멤버십처럼 만료가 없는 경우 `null`입니다.

**external\_accounts** `object[] | null` *required*

Discord, Telegram 등 외부 플랫폼에 있는 멤버의 계정입니다. 연결된 계정이 없으면 비어 있습니다. 웹훅에서는 `null`입니다.

> [accordion] 속성
>
> **external\_id** `string` *required*
>
> 플랫폼에서 멤버의 사용자 ID로, Discord 사용자 ID 등이 있습니다. 플랫폼 접두사가 붙은 형태(`discord_\<external_id>`)이며, List Memberships가 필터링에 사용하는 `external_account` 값입니다.
>
> **platform** `string` *required*
>
> 멤버의 계정이 있는 플랫폼입니다.
>
> 사용 가능한 옵션: `discord`, `telegram`
>
> **username** `string | null` *required*
>
> 플랫폼에서 멤버의 사용자 이름입니다. Discord ID만으로 가져온 멤버십처럼 Whop이 알지 못하는 경우 `null`입니다.

**feedback\_option** `object | null` *required*

멤버가 선택한 계정 자체의 취소 사유로, 멤버가 본 그대로입니다. 멤버가 기본 카테고리를 선택했거나 사유를 제공하지 않은 경우 `null`입니다.

> [accordion] 속성
>
> **label** `string` *required*
>
> 멤버가 선택했을 당시의 옵션 레이블입니다. 나중에 옵션 이름을 변경해도 바뀌지 않습니다.

**initial\_price** `object` *required*

베리언트 통화로 된 베리언트의 현재 선불 가격입니다. 정가이며, 반드시 구매자가 지불한 금액은 아닙니다. 첫 청구가 무료인 경우 `amount`는 `"0.00"`입니다.

> [accordion] 속성
>
> **amount** `string` *required*
>
> 주 단위 금액으로, 정확한 소수 문자열입니다. 예를 들어 `"10.00"`은 10달러입니다. 전송 중에 부동 소수점 반올림이 발생하지 않도록 문자열로 제공됩니다.
>
> **currency** `string` *required*
>
> 소문자로 된 세 자리 ISO 4217 통화 코드입니다.
>
> **decimals** `integer` *required*
>
> 금액이 가지는 소수 자릿수입니다. 청구 자체가 실행되는 정밀도입니다.
>
> **display\_decimals** `integer` *required*
>
> 표시할 소수 자릿수입니다. 일반적으로 `decimals`와 같지만 의도적으로 항상 같지는 않습니다: COP는 센타보 단위로 청구되지만 페소 단위로 표기되므로 각각 `2`와 `0`입니다. 이 값을 사용하여 자체 로캘에 맞게 숫자 형식을 지정하세요.

**license\_key** `string | null` *required*

이 멤버십의 소프트웨어 라이선스 키입니다. 상품에 소프트웨어 라이선스 경험이 포함된 경우에만 존재합니다.

**manage\_url** `string | null` *required*

구매자가 로그인하여 결제를 관리할 수 있는 URL입니다. 멤버 레코드가 없거나, 호출자가 구매자가 아니고 계정에 대한 `member:manage` 권한도 없는 경우 `null`입니다.

**member** `object | null` *required*

계정에서 호출자의 멤버 행입니다. 멤버십이 호출자에게 속한 경우에만 존재하며, 판매자 측 읽기에서는 `null`입니다.

> [accordion] 속성
>
> **access\_level** `string` *required*
>
> 멤버가 계정에서 접근할 수 있는 범위입니다: 결제 멤버는 `customer`, 팀원은 `admin`, 모든 권한이 만료되면 `no_access`입니다.
>
> 사용 가능한 옵션: `no_access`, `admin`, `customer`
>
> **last\_accessed\_at** `string | null` *required*
>
> 멤버가 계정의 콘텐츠를 마지막으로 연 시점으로, ISO 8601 타임스탬프입니다. 한 번도 연 적이 없는 경우 `null`입니다.
>
> **position** `number | null` *required*
>
> 구매자 자신의 계정 목록에서 멤버의 정렬 위치입니다. 구매자가 정렬할 때까지 `null`입니다.

**member\_id** `string | null` *required*

계정에서 구매자의 멤버 레코드로, 접두사는 `mber_`입니다. 청구되지 않은 멤버십처럼 멤버 레코드가 없는 경우 `null`입니다.

**metadata** `object` *required*

멤버십에 저장된 사용자 지정 키-값 쌍으로, 주로 소프트웨어 라이선스에 사용됩니다.

**most\_recent\_action** `string | null` *required*

멤버십의 최신 수명 주기 이벤트로, `renewing_on` 또는 `canceled_on` 등이 있습니다. `most_recent_action_at`과 함께 사용하세요. 기록된 것이 없는 경우 `null`입니다.

사용 가능한 옵션: `canceled_on`, `finished_split_pay_at`, `canceling_on`, `ending_on`, `renewing_on`, `past_due`, `next_payment_attempt`, `paused_at`, `trial_ends_at`, `unresolved_at`, `trial_canceling_on`

**most\_recent\_action\_at** `string | null` *required*

`most_recent_action`이 발생했거나 발생할 예정인 시점으로, ISO 8601 타임스탬프입니다. `renewing_on`처럼 예정된 이벤트의 경우 미래 시간입니다. 기록된 작업이 없는 경우 `null`입니다.

**phone\_number** `string | null` *required*

이 멤버십에 기록된 구매자의 전화번호이며, 없으면 `null`입니다. 판매자의 전화번호 수집이 켜져 있는 경우 체크아웃 시 수집(또는 인증)된 번호이며, 없으면 구매자가 이 판매자와 공유한 계정 번호로 대체됩니다.

**product** `object` *required*

이 멤버십이 접근 권한을 부여하는 상품입니다.

> [accordion] 속성
>
> **id** `string` *required*
>
> 상품 ID이며, 접두사는 `prod_`입니다.
>
> **logo\_url** `string | null` *required*
>
> 상품 로고 이미지 URL입니다. 상품에 로고가 없는 경우 `null`입니다.
>
> **title** `string` *required*
>
> 상품 표시 이름입니다.

**product\_id** `string` *required*

이 멤버십이 접근 권한을 부여하는 상품으로, 접두사는 `prod_`입니다.

**promo\_code\_id** `string | null` *required*

이 멤버십을 할인하는 프로모션 코드로, 접두사는 `promo_`입니다. 적용된 것이 없는 경우 `null`입니다. 체크아웃 시 또는 Apply Promo Code to Membership으로 설정됩니다.

**renewal\_price** `object | null` *required*

아직 적용 중인 프로모션 코드를 반영한, 베리언트 통화로 된 베리언트의 갱신 가격입니다. 구매자의 현지 통화로 청구되는 멤버십은 각 청구일의 환율로 환산된 이 가격이 청구됩니다. 갱신되지 않는 멤버십의 경우 `null`입니다.

> [accordion] 속성
>
> **amount** `string` *required*
>
> 주 단위 금액으로, 정확한 소수 문자열입니다. 예를 들어 `"10.00"`은 10달러입니다. 전송 중에 부동 소수점 반올림이 발생하지 않도록 문자열로 제공됩니다.
>
> **currency** `string` *required*
>
> 소문자로 된 세 자리 ISO 4217 통화 코드입니다.
>
> **decimals** `integer` *required*
>
> 금액이 가지는 소수 자릿수입니다. 청구 자체가 실행되는 정밀도입니다.
>
> **display\_decimals** `integer` *required*
>
> 표시할 소수 자릿수입니다. 일반적으로 `decimals`와 같지만 의도적으로 항상 같지는 않습니다: COP는 센타보 단위로 청구되지만 페소 단위로 표기되므로 각각 `2`와 `0`입니다. 이 값을 사용하여 자체 로캘에 맞게 숫자 형식을 지정하세요.

**split\_pay\_current\_payments** `integer | null` *required*

분할 결제 멤버십에서 지금까지 집계된 납부 완료 할부 횟수입니다. 멤버십이 분할 결제가 아니거나 첫 할부가 집계되기 전에는 `null`입니다.

**split\_pay\_required\_payments** `integer | null` *required*

멤버십 청구가 중단되기 전까지 필요한 할부 결제 횟수입니다. 멤버십이 분할 결제가 아닌 경우 `null`입니다.

**status** `string` *required*

멤버십의 결제 상태입니다. `active`/`trialing` 멤버십은 접근 권한을 부여하고, `past_due`는 결제 실패 후 유예 기간이며, `completed` 일회성 구매는 접근 권한을 유지하고, `canceled`/`expired`는 접근 권한이 없습니다.

사용 가능한 옵션: `trialing`, `active`, `past_due`, `completed`, `canceled`, `expired`, `unresolved`

**updated\_at** `string` *required*

멤버십이 마지막으로 변경된 시점으로, ISO 8601 타임스탬프입니다. 멤버십 자체의 가장 최근 변경을 반영하므로 웹훅 재시도, 재생, 백필과 대조할 수 있습니다.

**user\_id** `string | null` *required*

구매자로, 접두사는 `user_`입니다. 구매자가 다른 비즈니스이거나 멤버십이 청구되지 않은 경우 `null`입니다.

**variant\_id** `string` *required*

구매자가 구매한 베리언트로, 접두사는 `plan_`입니다.

```json Membership theme={null}
{
	"id": "mem_xxxxxxxxxxxxxx",
	"affiliate": null,
	"status": "active",
	"collection_method": "charge_automatically",
	"most_recent_action": "renewing_on",
	"most_recent_action_at": "2026-08-01T00:00:00.000Z",
	"user_id": "user_xxxxxxxxxxxxx",
	"product_id": "prod_xxxxxxxxxxxxx",
	"variant_id": "plan_xxxxxxxxxxxxx",
	"member_id": "mber_xxxxxxxxxxxxx",
	"product": {
		"id": "prod_xxxxxxxxxxxxx",
		"title": "Pickaxe Pro",
		"logo_url": "https://cdn.whop.com/product.png"
	},
	"initial_price": {
		"currency": "usd",
		"amount": "0.00",
		"decimals": 2,
		"display_decimals": 2
	},
	"renewal_price": {
		"currency": "usd",
		"amount": "50.00",
		"decimals": 2,
		"display_decimals": 2
	},
	"split_pay_current_payments": null,
	"split_pay_required_payments": null,
	"expires_at": null,
	"promo_code_id": null,
	"billing_period_days": 30,
	"license_key": "A1B2C3-D4E5F6-G7H8I9",
	"phone_number": "+12025550123",
	"cancel_at_period_end": false,
	"current_period_start": "2026-07-01T00:00:00.000Z",
	"current_period_end": "2026-08-01T00:00:00.000Z",
	"canceled_at": null,
	"cancel_option": null,
	"cancellation_reason": null,
	"feedback_option": null,
	"external_accounts": [
		{
			"platform": "discord",
			"external_id": "123456789012345678",
			"username": "jane"
		}
	],
	"manage_url": "https://whop.com/billing/manage/mber_xxxxxxxxxxxxx",
	"metadata": {
		"external_customer_id": "cus_123"
	},
	"created_at": "2026-07-01T00:00:00.000Z",
	"updated_at": "2026-07-15T00:00:00.000Z",
	"member": {
		"access_level": "customer",
		"last_accessed_at": "2026-07-20T15:30:00.000Z",
		"position": 1
	},
	"account": {
		"id": "biz_xxxxxxxxxxxxxx",
		"title": "Pickaxe",
		"route": "pickaxe",
		"logo_url": "https://cdn.whop.com/account.png"
	}
}
```
