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

# Variants API

> Variant는 상품의 구매 가능한 구성 하나입니다.

변형은 가격, 청구 주기, 재고, SKU, 속성, 세금 처리, 결제 필드, 구매 노출 여부를 제어합니다. 변형 ID는 계속 `plan_` 접두사를 사용합니다.

Variants API를 사용하여 상품의 변형을 생성하고, 기존 변형을 나열하고, 변형 구성을 조회하거나 업데이트하고, 결제를 위한 세금을 계산하고, 더 이상 제공하지 않을 변형을 삭제하세요.

## 엔드포인트

| 엔드포인트 | 요청 |
| - | - |
| [변형 목록 조회](https://docs.whop.com/ko/api-reference/variants/list-variants.md) | GET `/variants` |
| [변형 조회](https://docs.whop.com/ko/api-reference/variants/retrieve-variant.md) | GET `/variants/{id}` |
| [변형 생성](https://docs.whop.com/ko/api-reference/variants/create-variant.md) | POST `/variants` |
| [변형 업데이트](https://docs.whop.com/ko/api-reference/variants/update-variant.md) | PATCH `/variants/{id}` |
| [변형 삭제](https://docs.whop.com/ko/api-reference/variants/delete-variant.md) | DELETE `/variants/{id}` |

## 속성

**id** `string` *required*

변형 ID이며, 접두사는 `plan_`입니다.

**account** `object | null` *required*

이 변형을 판매하는 계정. 독립형 인보이스 변형의 경우 `null`입니다.

> [accordion] 속성
>
> **id** `string` *required*
>
> 계정 ID이며, 접두사는 `biz_`입니다.
>
> **title** `string` *required*
>
> 계정 표시 이름입니다.

**adaptive\_pricing\_enabled** `boolean` *required*

이 변형에 적응형 가격 책정이 활성화되어 있는지 여부. 원시 설정이며, 결제 처리업체 호환성이나 기능 플래그는 확인하지 않습니다.

**allow\_multiple\_quantity** `boolean` *required*

한 주문에서 두 개 이상의 단위를 구매할 수 있는지 여부. 갱신 변형에서는 활성화할 수 없습니다. `false`인 경우 결제, 장바구니, 인보이스에서 1을 초과하는 수량을 거부합니다.

**attributes** `object | null` *required*

상품 내에서 이 변형을 구별하는 속성 값으로, 속성 이름과 값의 맵입니다(예: `\{"color": "Blue", "size": "Large"}`). 이름은 snake\_case 식별자이며 알파벳 순으로 반환됩니다. 상품의 속성이 있는 모든 변형은 같은 속성 이름과 서로 다른 값 집합을 가지며, 상품은 전체 옵션 집합을 `variant_attributes`로 나열합니다. 변형에 속성이 없으면 `null`입니다.

**billing\_period** `number | null` *required*

반복 청구 사이의 일수로, 월간은 30, 연간은 365와 같습니다. 일회성 변형의 경우 `null`입니다.

**billing\_type** `string` *required*

이 변형의 청구 모델.

사용 가능한 옵션: `renewal`, `one_time`

**cancel\_discount\_intervals** `number | null` *required*

취소 할인이 지속되는 기간: `0`은 영구, `1`은 다음 결제에만, 또는 고객이 수락한 시점부터의 개월 수. 제공되는 할인이 없거나 행위자에게 `plan:basic:read` 범위가 없으면 `null`입니다.

**cancel\_discount\_percentage** `number | null` *required*

정수 백분율로 표시한 취소 할인. 제공되는 할인이 없거나 행위자에게 `plan:basic:read` 범위가 없으면 `null`입니다.

**checkout\_styling** `object | null` *required*

변형 수준의 결제 스타일(`background_color`, `button_color`, `font_family`, `border_style`). `null`이면 계정 기본값을 상속합니다.

**collect\_tax** `boolean` *required*

계정의 세금 구성에 따라 이 변형의 구매에 세금이 징수되는지 여부.

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

변형이 생성된 시점(ISO 8601 타임스탬프).

**currency** `string` *required*

이 변형의 모든 가격이 표시되는 통화의 소문자 3자리 ISO 4217 코드: 변형 자체의 통화, 또는 변형을 변환할 수 있는 경우 조회 시 요청한 `presentment_currency`.

**custom\_fields** `object[]` *required*

결제 양식에서 수집하는 커스텀 입력 필드.

> [accordion] 속성
>
> **id** `string` *required*
>
> 커스텀 필드 ID이며, 접두사는 `field_`입니다.
>
> **field\_type** `string` *required*
>
> 커스텀 필드 입력 유형.
>
> 사용 가능한 옵션: `text`
>
> **name** `string` *required*
>
> 결제 시 고객에게 표시되는 필드 레이블.
>
> **order** `number` *required*
>
> 결제 양식에서의 필드 위치.
>
> **placeholder** `string | null` *required*
>
> 빈 필드에 표시되는 자리 표시자 텍스트. 설정되지 않은 경우 `null`입니다.
>
> **required** `boolean` *required*
>
> 결제하기 위해 고객이 이 필드를 반드시 작성해야 하는지 여부.

**deletable** `boolean | null` *required*

변형을 삭제할 수 있는지 여부(멤버십이나 대기자 명단 항목이 없는 경우). 행위자가 변형 계정에 대한 `plan:basic:read` 범위를 가진 경우가 아니면 `null`입니다.

**description** `string | null` *required*

고객에게 표시되는 변형 설명. 최대 1000자. 설명이 설정되지 않은 경우 `null`입니다.

**effective\_payment\_method\_configuration** `object | null` *required*

모든 계층(변형 자체 및 계정)을 거쳐 해석된, 이 변형의 결제를 관리하는 구성으로, 세션의 `payment_method_configuration`이 가지는 형태입니다. 제공 가능한 집합을 얻으려면 결제 수단 유형 카탈로그에 적용하세요. `null`은 플랫폼 기본값을 의미하며, `payment_method_configuration`은 변형 자체의 편집 가능한 재정의로 유지됩니다.

> [accordion] 속성
>
> **disabled** `string[]` *required*
>
> 기본값이 제공하더라도 이 체크아웃에서 제외하는 결제 수단입니다.
>
> **enabled** `string[]` *required*
>
> 기본값이 제공하는 것에 더해 이 체크아웃에서 추가로 제공하는 결제 수단입니다.
>
> **include\_platform\_defaults** `boolean` *required*
>
> Whop의 기본 설정을 시작점으로 사용하는지 여부입니다. `false`이면 `enabled`만 제공됩니다.

**expiration\_days** `number | null` *required*

1년 이용권의 365처럼 만료 기반 변형의 액세스 기간(일). 만료가 없는 변형의 경우 `null`입니다.

**formatted\_price** `string` *required*

표시용으로 사람이 읽을 수 있는 `currency` 기준 가격(통화 + 간격). 예: "\$10 / month".

**image** `object | null` *required*

상품 페이지에 표시되는 가격 등급 이미지(`url`, `blurhash`). 이미지가 설정되지 않은 경우 `null`입니다.

**initial\_price** `number` *required*

`currency` 기준 초기 구매 가격.

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

프로모 코드와 세금 적용 전, 한 단위에 대해 결제 시 청구되는 총액: 반복 변형의 경우 `initial_price`에 첫 번째 `renewal_price`를 더한 값, 또는 무료 체험이 적용되는 동안에는 `initial_price`만. 조회하는 사용자가 이미 이 변형의 체험을 사용한 경우 체험은 적용되지 않습니다. `currency` 기준입니다.

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

**internal\_notes** `string | null` *required*

고객에게 표시되지 않는 비공개 메모. 행위자가 변형 계정에 대한 `plan:basic:read` 범위를 가진 경우가 아니면 `null`입니다.

**invoice** `object | null` *required*

이 변형이 생성된 대상 인보이스. 인보이스용으로 생성된 경우가 아니면 `null`입니다.

**member\_count** `number | null` *required*

이 변형을 통한 활성 멤버십. 행위자가 변형 계정에 대한 `plan:basic:read` 범위를 가진 경우가 아니면 `null`입니다.

**metadata** `object | null` *required*

변형에 저장된 커스텀 키-값 쌍. 결제 및 멤버십 이벤트의 웹훅 페이로드에 포함됩니다. 최대 50개 키, 키당 100자, 값당 500자. 예약된 키 `custom_cta`와 `custom_cta_url`이 설정되면 이 변형에 대해 상품의 결제 콜투액션을 재정의합니다.

**offer\_cancel\_discount** `boolean | null` *required*

취소 할인이 제공되는지 여부. 행위자가 변형 계정에 대한 `plan:basic:read` 범위를 가진 경우가 아니면 `null`입니다.

**payment\_method\_configuration** `object | null` *required*

결제 수단 구성(`enabled`, `disabled`, `include_platform_defaults`). 변형이 기본 설정을 사용하는 경우 `null`입니다.

**product** `object | null` *required*

이 변형이 속한 상품. 독립형 변형의 경우 `null`입니다.

**purchase\_url** `string` *required*

고객이 이 변형을 직접 구매할 수 있는 URL.

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

고객이 이 변형을 결제한 후 이동하는 곳. 설정되지 않았거나, 행위자가 변형 계정에 대한 `plan:basic:read` 범위를 가진 경우가 아니면 `null`입니다.

**release\_method** `string` *required*

이 변형의 판매 방식.

사용 가능한 옵션: `buy_now`, `waitlist`

**renewal\_price** `number` *required*

`currency` 기준으로 매 청구 기간마다 청구되는 반복 가격.

**sku** `string | null` *required*

판매자가 설정하는 자유 텍스트 재고 관리 단위(예: `TSHIRT-LARGE-BLUE`). 고유성이 강제되지 않습니다. 설정되지 않은 경우 `null`입니다.

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

구독이 일시 중지되기 전에 필요한 할부 결제 횟수. 1보다 커야 합니다. 분할 결제가 구성되지 않은 경우 `null`입니다.

**stock** `number | null` *required*

구매 가능한 단위 수. 행위자가 변형 계정에 대한 `plan:basic:read` 범위를 가진 경우가 아니면 `null`입니다.

**strike\_through\_initial\_price** `number | null` *required*

취소선과 함께 표시되는 `currency` 기준 원래 초기 가격. 취소선이 설정되지 않은 경우 `null`입니다.

**strike\_through\_renewal\_price** `number | null` *required*

취소선과 함께 표시되는 `currency` 기준 원래 갱신 가격. 취소선이 설정되지 않은 경우 `null`입니다.

**tax\_type** `string` *required*

세금이 가격에 포함되는지, 결제 시 추가되는지, 또는 구성되지 않았는지를 포함하여 이 변형의 세금 처리 방식.

사용 가능한 옵션: `inclusive`, `exclusive`, `unspecified`

**three\_ds\_level** `string | null` *required*

지원되는 온세션 카드 결제에 대한 3D Secure 동작입니다. `mandate_challenge`는 결제 처리 전에 3DS 챌린지를 요구하고, `mandate_if_required`는 결제 처리업체가 요구할 때에만 챌린지를 의무화하며, `frictionless_if_required`는 일반적인 프릭션리스 3DS 흐름을 사용합니다. \$1,000 이상의 결제는 `mandate_challenge`를 선택하지 않는 한 `mandate_if_required`를 사용합니다. 위험 및 인증 복구 요구 사항이 이 설정보다 우선할 수 있습니다. `null`이면 계정 기본값을 상속합니다.

사용 가능한 옵션: `mandate_challenge`, `mandate_if_required`, `frictionless_if_required`

**title** `string | null` *required*

고객에게 표시되는 변형 표시 이름. 최대 30자. 이름 없이 생성된 변형은 기본적으로 `/`로 연결된 속성 값을 사용합니다. 이름이 설정되지 않은 경우 `null`입니다.

**trial\_period\_days** `number | null` *required*

첫 갱신 청구 전 무료 체험 일수. 체험이 구성되지 않았거나 사용자가 이미 이 변형의 체험을 사용한 경우 `null`입니다.

**unlimited\_stock** `boolean` *required*

변형의 재고가 무제한인지 여부. `true`인 경우 `stock` 필드는 무시되며, 대기자 명단 변형은 항상 `true`를 보고합니다.

**unpaid\_invoice\_count** `integer | null` *required*

이 변형에 대해 발행되었지만 결제되거나 무효화되지 않은 인보이스 수. 이 값이 `0`보다 큰 동안에는 변형의 가격, 청구 기간, 체험, 결제 횟수, 통화 또는 청구 유형을 변경할 수 없습니다. 행위자가 변형 계정에 대한 `plan:basic:read` 범위를 가진 경우가 아니면 `null`입니다.

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

변형이 마지막으로 업데이트된 시점(ISO 8601 타임스탬프).

**visibility** `string` *required*

이 변형을 볼 수 있는 위치를 제어합니다. `hidden`인 경우 변형은 직접 링크로만 접근할 수 있습니다.

사용 가능한 옵션: `visible`, `hidden`, `archived`, `quick_link`

```json Variant theme={null}
{
	"id": "plan_xxxxxxxxxxxxx",
	"account": {
		"id": "biz_xxxxxxxxxxxxxx",
		"title": "Pickaxe"
	},
	"adaptive_pricing_enabled": true,
	"allow_multiple_quantity": false,
	"attributes": {
		"seats": "5",
		"tier": "Pro"
	},
	"billing_period": 30,
	"cancel_discount_intervals": null,
	"cancel_discount_percentage": null,
	"checkout_styling": null,
	"collect_tax": true,
	"created_at": "2023-12-01T05:00:00.401Z",
	"currency": "usd",
	"custom_fields": [
		{
			"id": "cusf_xxxxxxxxxxxx",
			"field_type": "text",
			"name": "Discord username",
			"order": 0,
			"placeholder": "e.g. pickaxe_user",
			"required": true
		}
	],
	"deletable": false,
	"description": "Monthly access to Pickaxe Analytics.",
	"expiration_days": null,
	"formatted_price": "$29.00 / month",
	"image": null,
	"initial_price": 29,
	"internal_notes": "Standard monthly variant",
	"redirect_url": null,
	"invoice": null,
	"member_count": 42,
	"metadata": {
		"external_plan_id": "monthly",
		"custom_cta": "subscribe",
		"custom_cta_url": "https://example.com/wash-club"
	},
	"offer_cancel_discount": false,
	"payment_method_configuration": {
		"enabled": ["card"],
		"disabled": [],
		"include_platform_defaults": true
	},
	"effective_payment_method_configuration": {
		"enabled": ["card"],
		"disabled": [],
		"include_platform_defaults": true
	},
	"billing_type": "renewal",
	"product": {
		"id": "prod_xxxxxxxxxxxxx",
		"title": "Pickaxe Analytics"
	},
	"purchase_url": "https://whop.com/pickaxe-analytics/checkout/plan_xxxxxxxxxxxxx",
	"release_method": "buy_now",
	"renewal_price": 29,
	"initial_price_due": {
		"currency": "usd",
		"amount": "29.00",
		"decimals": 2,
		"display_decimals": 2
	},
	"sku": "PICKAXE-PRO-5-MONTHLY",
	"split_pay_required_payments": null,
	"stock": null,
	"strike_through_initial_price": null,
	"strike_through_renewal_price": null,
	"tax_type": "exclusive",
	"three_ds_level": "frictionless_if_required",
	"title": "Pro / 5 seats",
	"trial_period_days": 7,
	"unlimited_stock": true,
	"unpaid_invoice_count": 0,
	"updated_at": "2023-12-01T05:00:00.401Z",
	"visibility": "visible"
}
```
