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

# Ad Campaigns API

> 광고 캠페인은 유료 광고의 최상위 컨테이너입니다. 하위 광고 그룹과 광고가 공유하는 목표와 예산 전략을 설정합니다.

광고 캠페인은 유료 광고의 최상위 컨테이너입니다. 하위 [광고 그룹](https://docs.whop.com/ko/api-reference/ad-groups/ad-group)과 광고가 공유하는 목표와 예산 전략을 설정합니다.

Ad Campaigns API를 사용하면 캠페인을 생성하고, 계정의 캠페인을 나열하고, 캠페인 설정을 조회하거나 업데이트하고, 캠페인 게재를 일시 중지하거나 재개할 수 있습니다.

광고 청구는 계정의 모든 캠페인에서 발생한 청구 대상 지출을 합산합니다. 결제가 실패하면 설정된 active/paused `status`는 유지되지만 `delivery_status: payment_failed`로 게재가 차단됩니다. 계정의 결제 수단을 수정하고 계정에 대해 [광고 결제를 한 번 재시도](https://docs.whop.com/ko/api-reference/accounts/retry-failed-ads-payments.md)하세요. 재시도는 비동기적으로 진행되며, 요청이 수락되었다고 해서 결제가 확정된 것은 아닙니다. 정산이 성공하면 차단이 해제되며, 활성 캠페인은 다른 요건을 충족하면 재개될 수 있고 일시 중지된 캠페인은 일시 중지 상태로 유지됩니다. [청구 및 재시도](https://docs.whop.com/ko/developer/ads/overview.md#paying-for-ads)를 참고하세요.

## 엔드포인트

| 엔드포인트 | 요청 |
| - | - |
| [광고 캠페인 목록 조회](https://docs.whop.com/ko/api-reference/ad-campaigns/list-ad-campaigns.md) | GET `/ad_campaigns` |
| [광고 캠페인 조회](https://docs.whop.com/ko/api-reference/ad-campaigns/retrieve-an-ad-campaign.md) | GET `/ad_campaigns/{id}` |
| [광고 캠페인 생성](https://docs.whop.com/ko/api-reference/ad-campaigns/create-an-ad-campaign.md) | POST `/ad_campaigns` |
| [광고 캠페인 복제](https://docs.whop.com/ko/api-reference/ad-campaigns/duplicate-an-ad-campaign.md) | POST `/ad_campaigns/{id}/duplicate` |
| [광고 캠페인 일시 중지](https://docs.whop.com/ko/api-reference/ad-campaigns/pause-an-ad-campaign.md) | POST `/ad_campaigns/{id}/pause` |
| [실패한 광고 캠페인 결제 재시도](https://docs.whop.com/ko/api-reference/ad-campaigns/retry-a-failed-ad-campaign-payment.md) | POST `/ad_campaigns/{id}/retry_payment` |
| [광고 캠페인 일시 중지 해제](https://docs.whop.com/ko/api-reference/ad-campaigns/unpause-an-ad-campaign.md) | POST `/ad_campaigns/{id}/unpause` |
| [광고 캠페인 업데이트](https://docs.whop.com/ko/api-reference/ad-campaigns/update-an-ad-campaign.md) | PATCH `/ad_campaigns/{id}` |
| [광고 캠페인 삭제](https://docs.whop.com/ko/api-reference/ad-campaigns/delete-an-ad-campaign.md) | DELETE `/ad_campaigns/{id}` |

## 속성

**id** `string` *required*

`adcamp_` 접두사가 붙은 광고 캠페인의 고유 식별자입니다.

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

이 캠페인을 운영하는 비즈니스와, 광고에 표시되는 그 이름 및 로고입니다.

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

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

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

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

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

**budget\_amount** `number | null` *required*

캠페인의 예산(USD)으로, 예산이 저장되고 청구되는 통화입니다. 대신 각 광고 그룹이 자체 예산을 설정하면 `null`입니다.

**budget\_amount\_local** `number | null` *required*

계정의 광고 보고 통화로 표시하기 위해 오늘 환율로 `budget_currency`로 나타낸 동일한 예산입니다. `budget_amount`가 `null`이면 `null`입니다.

**budget\_currency** `string` *required*

`budget_amount_local`의 ISO 4217 코드로, 계정의 `ads_reporting_currency` 설정입니다. 계정이 변경하지 않았다면 `usd`입니다.

**budget\_optimization** `string | null` *required*

예산을 소유하는 수준입니다. 캠페인 전체(`ad_campaign`) 또는 각 광고 그룹 개별(`ad_group`) 중 하나입니다.

사용 가능한 옵션: `ad_campaign`, `ad_group`

**budget\_type** `string | null` *required*

`budget_amount`를 하루 단위로 지출하는지(`daily`), 캠페인 전체 기간에 걸쳐 지출하는지(`lifetime`) 여부입니다.

사용 가능한 옵션: `daily`, `lifetime`

**campaign\_type** `string` *required*

생성 시 고정되는 캠페인 종류입니다. `standard`는 이미지 및 동영상 광고를 게재하고, `search`는 광고 그룹의 키워드에 대한 검색 결과에 텍스트 광고를 표시합니다.

사용 가능한 옵션: `standard`, `search`

**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 픽셀에 귀속된 문의 이벤트 수(라스트 클릭 기준)입니다.

**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 타임스탬프)입니다.

**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*

캠페인의 광고가 현재 게재 중인지 여부와, 게재 중이 아니라면 그 이유입니다. 콘텐츠 검토 중이면 in\_review이고, 시작을 기다리는 캠페인은 processing입니다. 계정 청구 실패 시 설정된 status는 변경하지 않고 payment\_failed로 설정됩니다. 결제 재시도에 성공하면 차단이 해제되고 게재 상태가 다시 계산됩니다. 여러 상태가 동시에 해당하면 우선순위가 가장 높은 상태가 반환됩니다.

사용 가능한 옵션: `payment_failed`, `all_ads_rejected`, `draft`, `paused`, `in_review`, `learning`, `processing`, `revise_content`, `issues`, `scheduled`, `completed`, `active`

**desired\_cost\_per\_result** `number | null`

광고주가 이 캠페인에서 달성하고자 하는 결과당 비용(USD)입니다. 목표값일 뿐이며 입찰가, 비용 한도, 입찰 한도가 아니고 캠페인 광고의 입찰 방식을 바꾸지 않습니다. 목표가 설정되지 않으면 `null`입니다.

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

캠페인 게재가 종료되는 시각(ISO 8601 타임스탬프)입니다. 일시 중지할 때까지 게재되거나 광고 그룹이 자체 일정을 설정하면 `null`입니다.

**frequency** `number | null` *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 픽셀이 기록합니다. 모든 광고 플랫폼에서 동일한 방식으로 집계됩니다.

**objective** `string | null` *required*

캠페인이 최적화하는 목표입니다. `awareness`는 폐지되기 전에 생성된 캠페인에만 나타나며, 그런 캠페인은 게재를 시작할 수 없습니다.

사용 가능한 옵션: `awareness`, `traffic`, `engagement`, `leads`, `sales`

**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 픽셀에 귀속된 일정 예약 이벤트 수(라스트 클릭 기준)입니다.

**special\_ad\_categories** `string[]` *required*

캠페인이 해당한다고 선언된 규제 카테고리입니다. 이 카테고리의 광고에는 추가 타기팅 제한이 적용됩니다. 해당 사항이 없으면 비어 있습니다.

사용 가능한 옵션: `housing`, `employment`, `financial_products`, `politics`

**spend** `number` *required*

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

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

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

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

캠페인 게재가 시작되는 시각(ISO 8601 타임스탬프)입니다. 게재 시작 즉시 시작되거나 광고 그룹이 자체 일정을 설정하면 `null`입니다.

**status** `string` *required*

광고 캠페인에 설정된 수명 주기 상태입니다. 청구 실패 시 이 값은 active 또는 paused로 유지되고 delivery\_status가 payment\_failed로 설정됩니다.

사용 가능한 옵션: `active`, `paused`, `inactive`, `payment_failed`, `draft`, `duplicating`

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

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

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

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

**target\_cost\_per\_result** `number | null` *required*

`target_result_event`에 대한 목표 결과당 비용(USD)입니다. 설정되지 않으면 `null`입니다.

**target\_result\_event** `string | null` *required*

`target_cost_per_result`의 단가 기준이 되는 이벤트로, `purchase`나 `lead` 등입니다. 캠페인에 단일 목표가 없으면 `null`입니다.

**title** `string` *required*

광고 캠페인의 표시 이름입니다.

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

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

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

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

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

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

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

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

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

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

```json AdCampaign theme={null}
{
	"id": "adcamp_xxxxxxxxxx",
	"account": {
		"id": "biz_xxxxxxxxxxxxx",
		"title": "Acme Studio",
		"route": "acme-studio",
		"logo_url": "https://img.whop.com/acme-studio-logo.png"
	},
	"added_to_cart_value": 2100,
	"added_to_carts": 42,
	"budget_amount": 250,
	"budget_amount_local": 250,
	"budget_currency": "usd",
	"budget_optimization": "ad_campaign",
	"budget_type": "daily",
	"campaign_type": "standard",
	"click_through_rate": 0.032,
	"clicks": 1200,
	"completed_registration_value": 0,
	"completed_registrations": 28,
	"contact_value": 0,
	"contacts": 18,
	"cost_per_added_to_cart": 17.86,
	"cost_per_click": 0.63,
	"cost_per_completed_registration": 26.79,
	"cost_per_contact": 41.67,
	"cost_per_lead": 30,
	"cost_per_mille": 20,
	"cost_per_purchase": 50,
	"cost_per_result": 50,
	"cost_per_schedule": null,
	"cost_per_submitted_application": null,
	"cost_per_unique_click": 0.74,
	"cost_per_viewed_content": 1.25,
	"created_at": "2026-06-01T12:00:00Z",
	"custom_conversions": 10,
	"custom_event_counts": {
		"QualifiedCall": 7,
		"BookedDemo": 3
	},
	"custom_event_values": {
		"QualifiedCall": 3500,
		"BookedDemo": 0
	},
	"delivery_status": "issues",
	"ends_at": null,
	"frequency": 2.1,
	"impressions": 37500,
	"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": "adcamp_xxxxxxxxxx",
			"resource_type": "ad_campaign"
		}
	],
	"lead_value": 1250,
	"leads": 25,
	"link_clicks": 960,
	"objective": "sales",
	"purchase_value": 12600,
	"purchases": 15,
	"reach": 17800,
	"result_event": "purchase",
	"result_event_name": null,
	"results": 15,
	"return_on_ad_spend": 16.8,
	"schedule_value": 0,
	"schedules": 0,
	"special_ad_categories": [],
	"spend": 750,
	"spend_currency": "usd",
	"starts_at": null,
	"status": "active",
	"submitted_application_value": 0,
	"submitted_applications": 0,
	"target_cost_per_result": 12.5,
	"target_result_event": "purchase",
	"title": "Pickaxe Pro launch",
	"unique_click_through_rate": 0.027,
	"unique_clicks": 1010,
	"updated_at": "2026-06-02T12:00:00Z",
	"viewed_content_value": 0,
	"viewed_contents": 600
}
```


## Related topics

- [Ad Campaigns](https://docs.whop.com/ko/api-reference/legacy/ad-campaigns/ad-campaign.md)
- [Delete an Ad Campaign](https://docs.whop.com/ko/api-reference/ad-campaigns/delete-an-ad-campaign.md)
- [Ad campaign updated](https://docs.whop.com/ko/api-reference/ad-campaigns/ad-campaign-updated.md)
