대부분의 앱은 멤버십을 관리할 필요가 전혀 없습니다. 관리자 도구, 고객 지원 흐름, 또는 사용자가 일시 중지하거나 취소할 수 있는 셀프 서비스 대시보드를 구축할 때 이 메서드를 사용하세요.
수명 주기 한눈에 보기
| 작업 | 메서드 | 기능 |
|---|---|---|
| 청구 일시 중지 | memberships.pause | 재개할 때까지 향후 갱신을 중지합니다. 기존 액세스는 유지됩니다. |
| 청구 재개 | memberships.resume | 일시 중지를 되돌립니다. |
| 취소 | memberships.cancel | 기간 종료 시 또는 즉시(기본값) 취소합니다. |
| 취소 복원 | memberships.update | cancel_at_period_end: false를 보내 대기 중인 취소를 되돌립니다. |
| 무료 기간 제공 | memberships.extend | 다음 갱신일을 N일 연장합니다. |
| 청구일 변경 | memberships.update | current_period_end를 보내 다음 갱신을 옮깁니다. 30, 60, 90 … 360 또는 365일마다 청구되는 멤버십은 해당 월의 같은 날에 계속 갱신됩니다. |
| 메타데이터 업데이트 | memberships.update | 메타데이터 또는 기타 쓰기 가능한 필드를 수정합니다. |
조회 및 목록
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);
}
membership = client.memberships.retrieve("mem_xxxxxxxxxxxxx")
for item in client.memberships.list(account_id="biz_xxxxxxxxxxxxx"):
print(item)
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
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:?}");
}
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을 전달하면 자동 재개를 예약할 수 있습니다.
await client.memberships.pause({
id: "mem_xxxxxxxxxxxxx",
until: "2026-09-01T00:00:00Z", // optional, resumes automatically
});
// Later
await client.memberships.resume({ id: "mem_xxxxxxxxxxxxx" });
client.memberships.pause(
"mem_xxxxxxxxxxxxx",
until="2026-09-01T00:00:00Z", # optional, resumes automatically
)
client.memberships.resume("mem_xxxxxxxxxxxxx")
client.memberships.pause(
id: "mem_xxxxxxxxxxxxx",
until: "2026-09-01T00:00:00Z", # optional, resumes automatically
)
# Later
client.memberships.resume(id: "mem_xxxxxxxxxxxxx")
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?;
_, 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를 전달하면 즉시 액세스가 취소됩니다.
// 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",
});
# 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",
)
# 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",
)
// 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?;
// 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)
}
cancel_at_period_end: true는 멤버십의 cancel_at_period_end를 true로 바꿉니다. 사용자는 갱신 시점까지 액세스를 유지하며, 이후 멤버십이 비활성화되고 이전 상태가 previous_attributes.status에 설정된 membership.updated가 발생합니다. 이 필드를 생략하면 즉시 액세스가 취소되므로, 기간 종료 시 취소하려는 경우에는 항상 명시적으로 보내세요.취소 복원하기
사용자가 기간이 끝나기 전에 마음을 바꾸면 업데이트로 대기 중인 기간 종료 취소를 해제하세요. 멤버십이 취소 예정이 아니었다면 아무런 영향이 없습니다.await client.memberships.update({
id: "mem_xxxxxxxxxxxxx",
cancel_at_period_end: false,
});
client.memberships.update("mem_xxxxxxxxxxxxx", cancel_at_period_end=False)
client.memberships.update(id: "mem_xxxxxxxxxxxxx", cancel_at_period_end: false)
client
.memberships
.update(
&"mem_xxxxxxxxxxxxx".to_string(),
&UpdateMembershipsRequest {
cancel_at_period_end: Some(false),
..Default::default()
},
None,
)
.await?;
if _, err := client.Memberships.Update(context.TODO(), &whopsdk.UpdateMembershipsRequest{
ID: "mem_xxxxxxxxxxxxx",
CancelAtPeriodEnd: whopsdk.Bool(false),
}); err != nil {
log.Fatal(err)
}
무료 일수 추가하기
사용자의 현재 기간에 추가 시간을 무료로 제공하세요. 다음 갱신일이days만큼 뒤로 이동합니다. 서비스 중단, 지원 차원의 보상, 추천 보상 등에 유용합니다.
await client.memberships.extend({
id: "mem_xxxxxxxxxxxxx",
days: 7,
});
client.memberships.extend("mem_xxxxxxxxxxxxx", days=7)
client.memberships.extend(id: "mem_xxxxxxxxxxxxx", days: 7)
client
.memberships
.extend(
&"mem_xxxxxxxxxxxxx".to_string(),
&ExtendMembershipsRequest { days: 7 },
None,
)
.await?;
if _, err := client.Memberships.Extend(context.TODO(), &whopsdk.ExtendMembershipsRequest{
ID: "mem_xxxxxxxxxxxxx",
Days: 7,
}); err != nil {
log.Fatal(err)
}
days는 1부터 1095(3년)까지 허용합니다.
메타데이터 업데이트하기
멤버십의 임의 메타데이터 또는 기타 쓰기 가능한 필드를 수정하세요.await client.memberships.update({
id: "mem_xxxxxxxxxxxxx",
metadata: { internal_user_id: "user_12345", tier: "gold" },
});
client.memberships.update(
"mem_xxxxxxxxxxxxx",
metadata={"internal_user_id": "user_12345", "tier": "gold"},
)
client.memberships.update(
id: "mem_xxxxxxxxxxxxx",
metadata: { internal_user_id: "user_12345", tier: "gold" },
)
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?;
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)
}
수명 주기 이벤트 수신하기
웹훅을 통해 구독하세요. 수명 주기 전반에 걸쳐 발생하는 이벤트는 다음과 같습니다:| 이벤트 | 발생 시점 |
|---|---|
membership.activated | 멤버십이 유효해질 때(최초 구매 또는 갱신 결제 성공). |
membership.updated | 멤버십의 무언가가 변경되었을 때. 멤버십이 무효화된 경우(결제 실패, 즉시 취소, 기간 종료 취소 적용, 사용자 탈퇴), 사용자가 취소를 켜거나 끈 경우, 판매자가 청구 기간, 가격, 갱신일을 수정한 경우입니다. previous_attributes에는 변경 전 값이 담깁니다. 활성화도 membership.updated로 전달됩니다. |
pause / resume / extend의 경우 멤버십 상태가 바뀌지 않으므로 활성화/비활성화 이벤트가 발생하지 않습니다. 변경이 성공했는지 확인해야 한다면 호출 후 멤버십을 조회하거나 자체 일정에 따라 폴링하세요.
다음 단계
결제 받기
멤버십이 생성되는 곳입니다. 일회성 및 정기 체크아웃.
결제 수단 저장
향후 갱신 및 오프세션 청구를 위해 등록된 카드입니다.
웹훅 수신하기
활성화, 비활성화, 취소 전환에 대응하세요.
멤버십 API 레퍼런스
전체 리소스: 필드, 상태, 모든 엔드포인트.

