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

# Ads API

> 광고는 광고 그룹이 게재하는 개별 크리에이티브 단위입니다. 광고 하나의 문구, 크리에이티브 에셋, 도착 URL을 담고 있습니다.

광고는 [광고 그룹](https://docs.whop.com/ko/api-reference/ad-groups/ad-group)이 게재하는 개별 크리에이티브 단위입니다. 광고 하나의 문구, 크리에이티브 에셋, 도착 URL을 담고 있습니다.

Ads API를 사용하면 계정의 광고를 나열하고, 광고 그룹 안에 광고를 생성하고, 크리에이티브 세부 정보를 조회하거나 업데이트하고, 더 이상 게재하지 않을 광고를 삭제하고, 게재를 일시 중지하거나 재개할 수 있습니다.

## 엔드포인트

| 엔드포인트 | 요청 |
| - | - |
| [광고 목록 조회](https://docs.whop.com/ko/api-reference/ads/list-ads.md) | GET `/ads` |
| [광고 조회](https://docs.whop.com/ko/api-reference/ads/retrieve-an-ad.md) | GET `/ads/{id}` |
| [광고 생성](https://docs.whop.com/ko/api-reference/ads/create-an-ad.md) | POST `/ads` |
| [광고 복제](https://docs.whop.com/ko/api-reference/ads/duplicate-an-ad.md) | POST `/ads/{id}/duplicate` |
| [광고 일시 중지](https://docs.whop.com/ko/api-reference/ads/pause-an-ad.md) | POST `/ads/{id}/pause` |
| [광고 일시 중지 해제](https://docs.whop.com/ko/api-reference/ads/unpause-an-ad.md) | POST `/ads/{id}/unpause` |
| [광고 업데이트](https://docs.whop.com/ko/api-reference/ads/update-an-ad.md) | PATCH `/ads/{id}` |
| [광고 삭제](https://docs.whop.com/ko/api-reference/ads/delete-an-ad.md) | DELETE `/ads/{id}` |

## 속성

**id** `string` *required*

`ad_` 접두사가 붙은 광고의 고유 식별자입니다.

**ad\_campaign** `object` *required*

이 광고가 속한 광고 캠페인입니다.

> [accordion] 속성
>
> **id** `string` *required*
>
> 참조된 엔터티의 ID입니다.

**ad\_group** `object` *required*

이 광고가 속한 광고 그룹입니다.

> [accordion] 속성
>
> **id** `string` *required*
>
> 참조된 엔터티의 ID입니다.

**added\_to\_cart\_value** `number` *required*

장바구니 담기 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.

**added\_to\_carts** `number` *required*

Whop 픽셀에 귀속된 장바구니 담기 이벤트 수(라스트 클릭 기준)입니다.

**call\_to\_action** `string | null` *required*

광고에 표시되는 클릭 유도 버튼입니다.

사용 가능한 옵션: `learn_more`, `shop_now`, `sign_up`, `subscribe`, `get_started`, `book_now`, `apply_now`, `contact_us`, `download`, `order_now`, `buy_now`, `get_quote`, `message_page`, `whatsapp_message`, `instagram_message`, `call_now`, `get_directions`, `send_updates`, `get_offer`, `watch_more`, `listen_now`, `play_game`, `open_link`, `no_button`, `get_offer_view`, `get_event_tickets`, `see_menu`, `request_time`, `event_rsvp`, `see_details`, `view_instagram_profile`, `donate_now`, `see_more`, `visit_site`

**click\_through\_rate** `number` *required*

클릭 수를 노출 수로 나눈 값으로, 0과 1 사이입니다.

**clicks** `number` *required*

클릭 수입니다.

**completed\_registration\_value** `number` *required*

등록 완료 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.

**completed\_registrations** `number` *required*

Whop 픽셀에 귀속된 등록 완료 이벤트 수(라스트 클릭 기준)입니다.

**contact\_value** `number` *required*

문의 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.

**contacts** `number` *required*

Whop 픽셀에 귀속된 문의 이벤트 수(라스트 클릭 기준)입니다.

**content\_review** `object` *required*

이 광고에 대한 Whop의 콘텐츠 검토입니다. 검토 완료 여부, 권장되는 광고 네트워크, 위반한 콘텐츠 규칙을 포함합니다.

> [accordion] 속성
>
> **networks** `object[]` *required*
>
> 각 네트워크가 광고를 게재할 수 있는지 여부입니다. 검토가 완료될 때까지 비어 있습니다.
>
> > [accordion] 속성
> >
> > **recommended** `boolean` *required*
> >
> > 광고가 Whop의 콘텐츠 정책과 이 네트워크의 정책을 통과하는지 여부입니다.
> >
> > **title** `string` *required*
> >
> > 네트워크입니다. `whop`은 Whop 자체 콘텐츠 정책으로, 다른 모든 네트워크에서도 요구됩니다.
> >
> > 사용 가능한 옵션: `whop`, `meta`, `tiktok`, `google`
>
> **status** `string` *required*
>
> Whop 콘텐츠 검토가 완료되면 `reviewed`, 진행 중이면 `in_review`, 실행된 적이 없으면 `not_reviewed`입니다.
>
> 사용 가능한 옵션: `reviewed`, `in_review`, `not_reviewed`
>
> **tags** `object[]` *required*
>
> 검토 결과 광고가 위반한 것으로 확인된 모든 네트워크의 규칙입니다. 위반한 규칙이 없거나 검토가 완료되지 않았으면 비어 있습니다.
>
> > [accordion] 속성
> >
> > **message** `string` *required*
> >
> > 검토에서 이 규칙에 대해 기록한 근거입니다.
> >
> > **title** `string` *required*
> >
> > Whop 콘텐츠 검토에서 광고가 위반한 것으로 확인된 규칙입니다.

**cost\_per\_added\_to\_cart** `number | null` *required*

지출을 귀속된 장바구니 담기 이벤트 수로 나눈 값입니다. 해당 이벤트가 목표가 아니고 귀속된 이벤트가 없으면 null입니다.

**cost\_per\_click** `number` *required*

지출을 클릭 수로 나눈 값입니다. 클릭이 없으면 0입니다.

**cost\_per\_completed\_registration** `number | null` *required*

지출을 귀속된 등록 완료 이벤트 수로 나눈 값입니다. 해당 이벤트가 목표가 아니고 귀속된 이벤트가 없으면 null입니다.

**cost\_per\_contact** `number | null` *required*

지출을 귀속된 문의 이벤트 수로 나눈 값입니다. 문의가 목표가 아니고 귀속된 이벤트가 없으면 null입니다.

**cost\_per\_lead** `number | null` *required*

지출을 귀속된 리드 수로 나눈 값입니다. 리드가 목표가 아니고 귀속된 리드가 없으면 null입니다.

**cost\_per\_mille** `number` *required*

노출 1,000회당 지출입니다. 노출이 없으면 0입니다.

**cost\_per\_purchase** `number | null` *required*

지출을 귀속된 구매 수로 나눈 값입니다. 구매가 목표가 아니고 귀속된 구매가 없으면 null입니다.

**cost\_per\_result** `number | null` *required*

지출을 Whop 픽셀에 귀속된 결과 수로 나눈 값입니다. Whop에 귀속될 수 있는 항목을 최적화하지 않으면 null입니다.

**cost\_per\_schedule** `number | null` *required*

지출을 귀속된 일정 예약 이벤트 수로 나눈 값입니다. 일정 예약이 목표가 아니고 귀속된 이벤트가 없으면 null입니다.

**cost\_per\_submitted\_application** `number | null` *required*

지출을 귀속된 신청서 제출 이벤트 수로 나눈 값입니다. 해당 이벤트가 목표가 아니고 귀속된 이벤트가 없으면 null입니다.

**cost\_per\_unique\_click** `number | null` *required*

지출을 고유 클릭 수로 나눈 값입니다. 고유 클릭이 없으면 null입니다.

**cost\_per\_viewed\_content** `number | null` *required*

지출을 귀속된 콘텐츠 조회 이벤트 수로 나눈 값입니다. 해당 이벤트가 목표가 아니고 귀속된 이벤트가 없으면 null입니다.

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

광고가 생성된 시각(ISO 8601 타임스탬프)입니다.

**creatives** `object[]` *required*

이 광고에 사용된 크리에이티브 에셋입니다. 원본 에셋의 format은 null이며, square, vertical, horizontal 항목은 게재 위치별 변형입니다. 캐러셀 광고는 첨부 파일마다 format이 null인 항목을 순서대로 하나씩 반환합니다.

> [accordion] 속성
>
> **id** `string` *required*
>
> 크리에이티브 첨부 파일의 파일 ID입니다.
>
> **crop** `object | null` *required*
>
> 이 크리에이티브에 저장된 크롭 영역으로, 원본 이미지 픽셀 단위입니다. 원본 에셋이거나 크롭되지 않은 format이면 null입니다.
>
> > [accordion] 속성
> >
> > **height** `number` *required*
> >
> > 원본 픽셀 단위의 크롭 영역 높이입니다.
> >
> > **width** `number` *required*
> >
> > 원본 픽셀 단위의 크롭 영역 너비입니다.
> >
> > **x** `number` *required*
> >
> > 원본 픽셀 단위의 크롭 영역 왼쪽 가장자리입니다.
> >
> > **y** `number` *required*
> >
> > 원본 픽셀 단위의 크롭 영역 위쪽 가장자리입니다.
>
> **format** `string | null` *required*
>
> 이 에셋이 해당하는 게재 위치 변형이며, 원본 에셋이면 null입니다.
>
> 사용 가능한 옵션: `square`, `vertical`, `horizontal`
>
> **language** `string | null` *required*
>
> 항상 `null`입니다. 번역은 더 이상 제공되지 않습니다.
>
> **media\_type** `string | null` *required*
>
> 에셋의 종류(이미지 또는 동영상)입니다.
>
> **url** `string | null` *required*
>
> 에셋의 CDN URL입니다.

**custom\_conversions** `number` *required*

모든 맞춤 이벤트 이름에 걸쳐 Whop 픽셀에 귀속된 맞춤(판매자 정의) 전환 이벤트 수(라스트 클릭 기준)입니다.

**custom\_event\_counts** `object` *required*

Whop 픽셀에 귀속된 맞춤 전환으로, 이벤트 이름을 키로, 라스트 클릭 기준 횟수를 값으로 가집니다. 귀속된 이름 있는 맞춤 이벤트가 없으면 비어 있습니다. 이름 없이 발생한 맞춤 이벤트는 custom\_conversions에는 집계되지만 여기서는 제외되므로, 이 값들의 합은 최대 custom\_conversions입니다.

**custom\_event\_values** `object` *required*

custom\_event\_counts와 마찬가지로 이벤트 이름을 키로 하여 각 맞춤 이벤트에 귀속된 전환 가치입니다. whop.track에 전달된 값을 USD로 정규화해 합산하며, 값 없이 발생한 이벤트는 0으로 계산됩니다.

**delivery\_status** `string` *required*

광고가 현재 게재 중인지 여부와, 게재 중이 아니라면 그 이유입니다. 여러 상태가 동시에 해당하면 우선순위가 가장 높은 상태가 반환됩니다.

사용 가능한 옵션: `rejected`, `in_review`, `draft`, `campaign_paused`, `paused`, `processing`, `revise_content`, `issues`, `scheduled`, `learning`, `active`

**descriptions** `object[]` *required*

광고에 표시되는 설명입니다.

> [accordion] 속성
>
> **language** `string | null` *required*
>
> 항상 `null`입니다. 번역은 더 이상 제공되지 않습니다.
>
> **text** `string` *required*
>
> 시청자에게 표시되는 텍스트입니다.

**frequency** `number | null` *required*

노출 수를 도달 수로 나눈 값입니다.

**headlines** `object[]` *required*

광고에 표시되는 헤드라인입니다.

> [accordion] 속성
>
> **language** `string | null` *required*
>
> 항상 `null`입니다. 번역은 더 이상 제공되지 않습니다.
>
> **text** `string` *required*
>
> 시청자에게 표시되는 텍스트입니다.

**impressions** `number` *required*

노출 수입니다.

**issues** `object[]` *required*

이 광고에 영향을 주는 미해결 이슈입니다. 없으면 비어 있습니다.

> [accordion] 속성
>
> **id** `string` *required*
>
> 이슈의 고유 식별자입니다.
>
> **category** `string` *required*
>
> 이슈의 종류입니다. 게재에 관한 정보, 경고 또는 조치가 필요한 오류 중 하나입니다.
>
> 사용 가능한 옵션: `information`, `warning`, `error`
>
> **message** `string` *required*
>
> 이슈의 내용과 해결 방법에 대한 설명입니다.
>
> **resource\_id** `string | null` *required*
>
> 이슈가 연결된 캠페인, 광고 그룹 또는 광고의 ID입니다.
>
> **resource\_type** `string` *required*
>
> 이슈가 연결된 리소스의 유형입니다.
>
> 사용 가능한 옵션: `ad_campaign`, `ad_group`, `ad`
>
> **title** `string` *required*
>
> 크리에이터에게 표시되는 이슈의 짧은 제목입니다. 콘텐츠 검토 거부 시 지목된 규칙 또는 일반 레이블입니다.

**lead\_value** `number` *required*

리드 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.

**leads** `number` *required*

Whop 픽셀에 귀속된 리드 수(라스트 클릭 기준)입니다.

**link\_clicks** `number` *required*

광고를 클릭한 사람들이 도착 페이지에서 발생시킨 페이지 조회 수로, Whop 픽셀이 기록합니다. 모든 광고 플랫폼에서 동일한 방식으로 집계됩니다.

**primary\_texts** `object[]` *required*

광고 본문에 표시되는 기본 텍스트입니다. 여러 항목을 지정하면 텍스트 변형이 만들어집니다.

> [accordion] 속성
>
> **language** `string | null` *required*
>
> 항상 `null`입니다. 번역은 더 이상 제공되지 않습니다.
>
> **text** `string` *required*
>
> 시청자에게 표시되는 텍스트입니다.

**purchase\_value** `number` *required*

픽셀에 귀속된 구매의 USD 가치입니다.

**purchases** `number` *required*

Whop 픽셀에 귀속된 구매 수(라스트 클릭 기준)입니다.

**reach** `number` *required*

이를 본 고유 사용자 수입니다.

**result\_event** `string | null` *required*

귀속된 횟수가 결과를 나타내는 Whop 픽셀 전환 이벤트입니다. 최적화 목표이거나, 광고 그룹별로 예산을 설정하는 캠페인의 경우 귀속된 횟수가 가장 많은 이벤트입니다. 목표가 Whop에 귀속되는 이벤트가 아니면 null입니다.

사용 가능한 옵션: `purchase`, `lead`, `schedule`, `submit_application`, `contact`, `complete_registration`, `view_content`, `add_to_cart`, `custom`, `messaging_conversation`

**result\_event\_name** `string | null` *required*

result\_event가 custom일 때의 판매자 정의 이벤트 이름입니다. 표준 이벤트에서는 null입니다.

**results** `number | null` *required*

result\_event의 기반이 되는 Whop 픽셀 귀속 횟수입니다. 캠페인의 광고 그룹들이 서로 다른 목표를 최적화하면 단일 result\_event가 없으며(null), 이 값은 대신 각 광고 그룹의 귀속 결과를 합산한 값입니다. Whop에 귀속될 수 있는 항목을 최적화하지 않으면 null입니다.

**return\_on\_ad\_spend** `number` *required*

구매 가치를 지출로 나눈 값으로, 둘 다 USD 기준입니다(통화 중립적인 비율). 지출이 없으면 0입니다.

**schedule\_value** `number` *required*

일정 예약 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.

**schedules** `number` *required*

Whop 픽셀에 귀속된 일정 예약 이벤트 수(라스트 클릭 기준)입니다.

**spend** `number` *required*

spend\_currency로 표시된 청구 금액입니다.

**spend\_currency** `string | null` *required*

모든 금액 지표의 ISO 4217 통화 코드입니다.

**status** `string` *required*

광고의 활성화 여부입니다. `active`와 `paused`는 사용자가 설정하며, `in_review`와 `rejected`는 광고 검토에서 설정됩니다.

사용 가능한 옵션: `active`, `paused`, `in_review`, `rejected`

**submitted\_application\_value** `number` *required*

신청서 제출 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.

**submitted\_applications** `number` *required*

Whop 픽셀에 귀속된 신청서 제출 이벤트 수(라스트 클릭 기준)입니다.

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

광고의 표시 제목입니다.

**unique\_click\_through\_rate** `number | null` *required*

고유 클릭 수를 노출 수로 나눈 값으로, 0과 1 사이입니다.

**unique\_clicks** `number` *required*

Whop 픽셀이 보고한 클릭한 사람 수로, 사람당 한 번만 집계됩니다.

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

광고가 마지막으로 업데이트된 시각(ISO 8601 타임스탬프)입니다.

**url** `string | null` *required*

광고가 연결되는 URL로, 쿼리 문자열은 포함하지 않습니다. 매개변수는 `url_parameters`에 넣어야 하며, `url`에 포함해 보낸 매개변수는 그곳으로 이동됩니다.

**url\_parameters** `object` *required*

이름을 키로 하여 `url`에 추가되는 쿼리 매개변수입니다. Whop의 클릭 기여 매개변수는 예약되어 있습니다.

**viewed\_content\_value** `number` *required*

콘텐츠 조회 이벤트에 귀속된 USD 가치입니다. 각 이벤트와 함께 전송된 값을 USD로 정규화해 합산하며, 값이 없는 이벤트는 0으로 계산됩니다.

**viewed\_contents** `number` *required*

Whop 픽셀에 귀속된 콘텐츠 조회 이벤트 수(라스트 클릭 기준)입니다.

```json Ad theme={null}
{
	"id": "ad_xxxxxxxxxxxxx",
	"ad_campaign": {
		"id": "adcamp_xxxxxxxxxx"
	},
	"ad_group": {
		"id": "adgrp_xxxxxxxxxxx"
	},
	"added_to_cart_value": 540,
	"added_to_carts": 18,
	"call_to_action": "shop_now",
	"click_through_rate": 0.034,
	"clicks": 420,
	"completed_registration_value": 0,
	"completed_registrations": 12,
	"contact_value": 0,
	"contacts": 8,
	"content_review": {
		"status": "reviewed",
		"networks": [
			{
				"title": "whop",
				"recommended": true
			},
			{
				"title": "meta",
				"recommended": true
			},
			{
				"title": "tiktok",
				"recommended": false
			},
			{
				"title": "google",
				"recommended": true
			}
		],
		"tags": [
			{
				"title": "Unrealistic earnings or investment claims",
				"message": "The ad promises viewers they will make $10,000 a month."
			}
		]
	},
	"cost_per_added_to_cart": 7.22,
	"cost_per_click": 0.31,
	"cost_per_completed_registration": 10.83,
	"cost_per_contact": 16.25,
	"cost_per_lead": 9.29,
	"cost_per_mille": 14.5,
	"cost_per_purchase": 21.67,
	"cost_per_result": 21.67,
	"cost_per_schedule": null,
	"cost_per_submitted_application": null,
	"cost_per_unique_click": 0.37,
	"cost_per_viewed_content": 0.54,
	"created_at": "2026-06-01T12:00:00Z",
	"creatives": [
		{
			"id": "file_xxxxxxxxxxxx",
			"crop": {
				"height": 1080,
				"width": 1080,
				"x": 120,
				"y": 0
			},
			"format": "square",
			"media_type": "image",
			"url": "https://img.whop.com/file_xxxxxxxxxxxx.jpg",
			"language": null
		}
	],
	"custom_conversions": 4,
	"custom_event_counts": {
		"QualifiedCall": 3,
		"BookedDemo": 1
	},
	"custom_event_values": {
		"QualifiedCall": 1500,
		"BookedDemo": 0
	},
	"delivery_status": "issues",
	"descriptions": [
		{
			"language": null,
			"text": "Limited spots available this week."
		}
	],
	"frequency": 1.8,
	"headlines": [
		{
			"language": null,
			"text": "Join Pickaxe Pro"
		}
	],
	"impressions": 9000,
	"issues": [
		{
			"id": "adiss_xxxxxxxxxxx",
			"category": "error",
			"title": "Ad issue",
			"message": "The ad's creative violates the ad network's policies. Edit the creative and resubmit for review.",
			"resource_id": "ad_xxxxxxxxxxxxx",
			"resource_type": "ad"
		}
	],
	"lead_value": 700,
	"leads": 14,
	"link_clicks": 336,
	"primary_texts": [
		{
			"language": null,
			"text": "Build sharper trading habits with daily lessons."
		}
	],
	"purchase_value": 1820,
	"purchases": 6,
	"reach": 5000,
	"result_event": "purchase",
	"result_event_name": null,
	"results": 6,
	"return_on_ad_spend": 14,
	"schedule_value": 0,
	"schedules": 0,
	"spend": 130,
	"spend_currency": "usd",
	"status": "active",
	"submitted_application_value": 0,
	"submitted_applications": 0,
	"title": "Pickaxe Pro launch ad",
	"unique_click_through_rate": 0.028,
	"unique_clicks": 350,
	"updated_at": "2026-06-02T12:00:00Z",
	"url": "https://whop.com/pickaxe",
	"url_parameters": {
		"utm_campaign": "pickaxe-launch"
	},
	"viewed_content_value": 0,
	"viewed_contents": 240
}
```
