> ## 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로 멤버십을 조회하고 구독 일시 중지나 무료 일수 추가와 같이 청구를 변경하세요.

멤버십은 사용자와 상품 간의 활성 관계입니다. 액세스, 청구 상태, 갱신 일정을 추적합니다. 체크아웃이 멤버십을 자동으로 생성하므로 직접 만들 필요는 없습니다. 멤버십이 생성되면 이를 조회하고, 청구를 일시 중지하거나 취소하고, 무료 기간을 제공하거나, 메타데이터를 업데이트할 수 있습니다.

> [!TIP]
>
> 대부분의 앱은 멤버십을 관리할 필요가 전혀 없습니다. 관리자 도구, 고객 지원 흐름, 또는 사용자가 일시 중지하거나 취소할 수 있는 셀프 서비스 대시보드를 구축할 때 이 메서드를 사용하세요.

## 수명 주기 한눈에 보기

| 작업 | 메서드 | 기능 |
| - | - | - |
| 청구 일시 중지 | [`memberships.pause`](https://docs.whop.com/ko/api-reference/memberships/pause-membership) | 재개할 때까지 향후 갱신을 중지합니다. 기존 액세스는 유지됩니다. |
| 청구 재개 | [`memberships.resume`](https://docs.whop.com/ko/api-reference/memberships/resume-membership) | 일시 중지를 되돌립니다. |
| 취소 | [`memberships.cancel`](https://docs.whop.com/ko/api-reference/memberships/cancel-membership) | 기간 종료 시 또는 즉시(기본값) 취소합니다. |
| 취소 복원 | [`memberships.update`](https://docs.whop.com/ko/api-reference/memberships/update-membership) | `cancel_at_period_end: false`를 보내 대기 중인 취소를 되돌립니다. |
| 무료 기간 제공 | [`memberships.extend`](https://docs.whop.com/ko/api-reference/memberships/extend-membership) | 다음 갱신일을 N일 연장합니다. |
| 청구일 변경 | [`memberships.update`](https://docs.whop.com/ko/api-reference/memberships/update-membership) | `current_period_end`를 보내 다음 갱신을 옮깁니다. 30, 60, 90 … 360 또는 365일마다 청구되는 멤버십은 해당 월의 같은 날에 계속 갱신됩니다. |
| 메타데이터 업데이트 | [`memberships.update`](https://docs.whop.com/ko/api-reference/memberships/update-membership) | 메타데이터 또는 기타 쓰기 가능한 필드를 수정합니다. |

## 조회 및 목록

```typescript TypeScript theme={null}
const membership = await client.memberships.retrieve({ id: "mem_xxxxxxxxxxxxx" });

// List with auto-pagination
const memberships = await client.memberships.list({
  account_id: "biz_xxxxxxxxxxxxx",
});

for await (const item of memberships) {
  console.log(item);
}
```

```python Python theme={null}
membership = client.memberships.retrieve("mem_xxxxxxxxxxxxx")

for item in client.memberships.list(account_id="biz_xxxxxxxxxxxxx"):
    print(item)
```

```ruby Ruby theme={null}
membership = client.memberships.retrieve(id: "mem_xxxxxxxxxxxxx")

# list returns an Enumerable that pages for you and yields one membership at a time
client.memberships.list(account_id: "biz_xxxxxxxxxxxxx").each do |item|
  puts item
end
```

```rust Rust theme={null}
let membership = client
    .memberships
    .retrieve(&"mem_xxxxxxxxxxxxx".to_string(), None)
    .await?;

// List one page of memberships for an account
let memberships = client
    .memberships
    .list(
        &MembershipsListQueryRequest {
            account_id: Some("biz_xxxxxxxxxxxxx".to_string()),
            ..Default::default()
        },
        None,
    )
    .await?;

for item in memberships.data {
    println!("{item:?}");
}
```

```go Go theme={null}
membership, err := client.Memberships.Retrieve(context.TODO(), &whopsdk.RetrieveMembershipsRequest{
    ID: "mem_xxxxxxxxxxxxx",
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(membership)

// List with auto-pagination
page, err := client.Memberships.List(context.TODO(), &whopsdk.ListMembershipsRequest{
    AccountID: whopsdk.String("biz_xxxxxxxxxxxxx"),
})
if err != nil {
    log.Fatal(err)
}

iter := page.Iterator()
for iter.Next(context.TODO()) {
    fmt.Println(iter.Current())
}
if err := iter.Err(); err != nil {
    log.Fatal(err)
}
```

## 일시 중지 및 재개

일시 중지하면 다음 청구 주기가 중지됩니다. 사용자는 현재 기간이 끝날 때까지 기존 액세스를 유지하지만 갱신은 실행되지 않습니다. `until`을 전달하면 자동 재개를 예약할 수 있습니다.

```typescript TypeScript theme={null}
await client.memberships.pause({
  id: "mem_xxxxxxxxxxxxx",
  until: "2026-09-01T00:00:00Z", // optional, resumes automatically
});

// Later
await client.memberships.resume({ id: "mem_xxxxxxxxxxxxx" });
```

```python Python theme={null}
client.memberships.pause(
    "mem_xxxxxxxxxxxxx",
    until="2026-09-01T00:00:00Z",  # optional, resumes automatically
)

client.memberships.resume("mem_xxxxxxxxxxxxx")
```

```ruby Ruby theme={null}
client.memberships.pause(
  id: "mem_xxxxxxxxxxxxx",
  until: "2026-09-01T00:00:00Z", # optional, resumes automatically
)

# Later
client.memberships.resume(id: "mem_xxxxxxxxxxxxx")
```

```rust Rust theme={null}
client
    .memberships
    .pause(
        &"mem_xxxxxxxxxxxxx".to_string(),
        &PauseMembershipsRequest {
            until: Some("2026-09-01T00:00:00Z".to_string()), // optional, resumes automatically
        },
        None,
    )
    .await?;

// Later
client.memberships.resume(&"mem_xxxxxxxxxxxxx".to_string(), None).await?;
```

```go Go theme={null}
_, err := client.Memberships.Pause(context.TODO(), &whopsdk.PauseMembershipsRequest{
    ID:    "mem_xxxxxxxxxxxxx",
    Until: whopsdk.String("2026-09-01T00:00:00Z"), // optional, resumes automatically
})
if err != nil {
    log.Fatal(err)
}

// Later
if _, err := client.Memberships.Resume(context.TODO(), &whopsdk.ResumeMembershipsRequest{
    ID: "mem_xxxxxxxxxxxxx",
}); err != nil {
    log.Fatal(err)
}
```

## 취소

취소 모드는 두 가지입니다. `cancel_at_period_end: true`는 현재 갱신일까지 액세스를 유지한 다음 비활성화합니다. 이를 생략하거나 `false`를 전달하면 즉시 액세스가 취소됩니다.

```typescript TypeScript theme={null}
// Cancel at the end of the current billing period
await client.memberships.cancel({
  id: "mem_xxxxxxxxxxxxx",
  cancel_at_period_end: true,
});

// Cancel immediately. Access ends now.
await client.memberships.cancel({
  id: "mem_xxxxxxxxxxxxx",
  cancel_at_period_end: false,
  reason: "Requested by customer",
});
```

```python Python theme={null}
# Cancel at the end of the current billing period
client.memberships.cancel(
    "mem_xxxxxxxxxxxxx",
    cancel_at_period_end=True,
)

# Cancel immediately. Access ends now.
client.memberships.cancel(
    "mem_xxxxxxxxxxxxx",
    cancel_at_period_end=False,
    reason="Requested by customer",
)
```

```ruby Ruby theme={null}
# Cancel at the end of the current billing period
client.memberships.cancel(
  id: "mem_xxxxxxxxxxxxx",
  cancel_at_period_end: true,
)

# Cancel immediately. Access ends now.
client.memberships.cancel(
  id: "mem_xxxxxxxxxxxxx",
  cancel_at_period_end: false,
  reason: "Requested by customer",
)
```

```rust Rust theme={null}
// Cancel at the end of the current billing period
client
    .memberships
    .cancel(
        &"mem_xxxxxxxxxxxxx".to_string(),
        &CancelMembershipsRequest {
            cancel_at_period_end: Some(true),
            ..Default::default()
        },
        None,
    )
    .await?;

// Cancel immediately. Access ends now.
client
    .memberships
    .cancel(
        &"mem_xxxxxxxxxxxxx".to_string(),
        &CancelMembershipsRequest {
            cancel_at_period_end: Some(false),
            reason: Some("Requested by customer".to_string()),
        },
        None,
    )
    .await?;
```

```go Go theme={null}
// Cancel at the end of the current billing period
_, err := client.Memberships.Cancel(context.TODO(), &whopsdk.CancelMembershipsRequest{
    ID:                "mem_xxxxxxxxxxxxx",
    CancelAtPeriodEnd: whopsdk.Bool(true),
})
if err != nil {
    log.Fatal(err)
}

// Cancel immediately. Access ends now.
_, err = client.Memberships.Cancel(context.TODO(), &whopsdk.CancelMembershipsRequest{
    ID:                "mem_xxxxxxxxxxxxx",
    CancelAtPeriodEnd: whopsdk.Bool(false),
    Reason:            whopsdk.String("Requested by customer"),
})
if err != nil {
    log.Fatal(err)
}
```

> [!NOTE]
>
> `cancel_at_period_end: true`는 멤버십의 `cancel_at_period_end`를 `true`로 바꿉니다. 사용자는 갱신 시점까지 액세스를 유지하며, 이후 멤버십이 비활성화되고 이전 상태가 `previous_attributes.status`에 설정된 `membership.updated`가 발생합니다. 이 필드를 생략하면 즉시 액세스가 취소되므로, 기간 종료 시 취소하려는 경우에는 항상 명시적으로 보내세요.

## 취소 복원하기

사용자가 기간이 끝나기 전에 마음을 바꾸면 업데이트로 대기 중인 기간 종료 취소를 해제하세요. 멤버십이 취소 예정이 아니었다면 아무런 영향이 없습니다.

```typescript TypeScript theme={null}
await client.memberships.update({
  id: "mem_xxxxxxxxxxxxx",
  cancel_at_period_end: false,
});
```

```python Python theme={null}
client.memberships.update("mem_xxxxxxxxxxxxx", cancel_at_period_end=False)
```

```ruby Ruby theme={null}
client.memberships.update(id: "mem_xxxxxxxxxxxxx", cancel_at_period_end: false)
```

```rust Rust theme={null}
client
    .memberships
    .update(
        &"mem_xxxxxxxxxxxxx".to_string(),
        &UpdateMembershipsRequest {
            cancel_at_period_end: Some(false),
            ..Default::default()
        },
        None,
    )
    .await?;
```

```go Go theme={null}
if _, err := client.Memberships.Update(context.TODO(), &whopsdk.UpdateMembershipsRequest{
    ID:                "mem_xxxxxxxxxxxxx",
    CancelAtPeriodEnd: whopsdk.Bool(false),
}); err != nil {
    log.Fatal(err)
}
```

## 무료 일수 추가하기

사용자의 현재 기간에 추가 시간을 무료로 제공하세요. 다음 갱신일이 `days`만큼 뒤로 이동합니다. 서비스 중단, 지원 차원의 보상, 추천 보상 등에 유용합니다.

```typescript TypeScript theme={null}
await client.memberships.extend({
  id: "mem_xxxxxxxxxxxxx",
  days: 7,
});
```

```python Python theme={null}
client.memberships.extend("mem_xxxxxxxxxxxxx", days=7)
```

```ruby Ruby theme={null}
client.memberships.extend(id: "mem_xxxxxxxxxxxxx", days: 7)
```

```rust Rust theme={null}
client
    .memberships
    .extend(
        &"mem_xxxxxxxxxxxxx".to_string(),
        &ExtendMembershipsRequest { days: 7 },
        None,
    )
    .await?;
```

```go Go theme={null}
if _, err := client.Memberships.Extend(context.TODO(), &whopsdk.ExtendMembershipsRequest{
    ID:   "mem_xxxxxxxxxxxxx",
    Days: 7,
}); err != nil {
    log.Fatal(err)
}
```

`days`는 1부터 1095(3년)까지 허용합니다.

## 메타데이터 업데이트하기

멤버십의 임의 메타데이터 또는 기타 쓰기 가능한 필드를 수정하세요.

```typescript TypeScript theme={null}
await client.memberships.update({
  id: "mem_xxxxxxxxxxxxx",
  metadata: { internal_user_id: "user_12345", tier: "gold" },
});
```

```python Python theme={null}
client.memberships.update(
    "mem_xxxxxxxxxxxxx",
    metadata={"internal_user_id": "user_12345", "tier": "gold"},
)
```

```ruby Ruby theme={null}
client.memberships.update(
  id: "mem_xxxxxxxxxxxxx",
  metadata: { internal_user_id: "user_12345", tier: "gold" },
)
```

```rust Rust theme={null}
client
    .memberships
    .update(
        &"mem_xxxxxxxxxxxxx".to_string(),
        &UpdateMembershipsRequest {
            metadata: Some(HashMap::from([
                ("internal_user_id".to_string(), json!("user_12345")),
                ("tier".to_string(), json!("gold")),
            ])),
            ..Default::default()
        },
        None,
    )
    .await?;
```

```go Go theme={null}
if _, err := client.Memberships.Update(context.TODO(), &whopsdk.UpdateMembershipsRequest{
    ID: "mem_xxxxxxxxxxxxx",
    Metadata: map[string]any{
        "internal_user_id": "user_12345",
        "tier":             "gold",
    },
}); err != nil {
    log.Fatal(err)
}
```

## 수명 주기 이벤트 수신하기

[웹훅](https://docs.whop.com/ko/developer/guides/webhooks.md)을 통해 구독하세요. 수명 주기 전반에 걸쳐 발생하는 이벤트는 다음과 같습니다:

| 이벤트 | 발생 시점 |
| - | - |
| [`membership.activated`](https://docs.whop.com/ko/api-reference/memberships/membership-activated) | 멤버십이 유효해질 때(최초 구매 또는 갱신 결제 성공). |
| [`membership.updated`](https://docs.whop.com/ko/api-reference/memberships/membership-updated) | 멤버십의 무언가가 변경되었을 때. 멤버십이 무효화된 경우(결제 실패, 즉시 취소, 기간 종료 취소 적용, 사용자 탈퇴), 사용자가 취소를 켜거나 끈 경우, 판매자가 청구 기간, 가격, 갱신일을 수정한 경우입니다. `previous_attributes`에는 변경 전 값이 담깁니다. 활성화도 `membership.updated`로 전달됩니다. |

`pause` / `resume` / `extend`의 경우 멤버십 상태가 바뀌지 않으므로 활성화/비활성화 이벤트가 발생하지 않습니다. 변경이 성공했는지 확인해야 한다면 호출 후 멤버십을 조회하거나 자체 일정에 따라 폴링하세요.

## 다음 단계

> [card] [결제 받기](https://docs.whop.com/ko/developer/guides/accept-payments.md)
>
> 멤버십이 생성되는 곳입니다. 일회성 및 정기 체크아웃.

> [card] [결제 수단 저장](https://docs.whop.com/ko/developer/guides/save-payment-methods.md)
>
> 향후 갱신 및 오프세션 청구를 위해 등록된 카드입니다.

> [card] [웹훅 수신하기](https://docs.whop.com/ko/developer/guides/webhooks.md)
>
> 활성화, 비활성화, 취소 전환에 대응하세요.

> [card] [멤버십 API 레퍼런스](https://docs.whop.com/ko/api-reference/memberships/membership)
>
> 전체 리소스: 필드, 상태, 모든 엔드포인트.


## Related topics

- [Memberships API](https://docs.whop.com/ko/api-reference/memberships/membership.md)
- [iOS Checkout SDK 레퍼런스](https://docs.whop.com/ko/developer/guides/ios/checkout-reference.md)
- [API 버전](https://docs.whop.com/ko/developer/api/versioning.md)
