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

# Whop Ads로 광고하기

> Whop 계정을 통해 외부 광고 네트워크에 광고를 구매하고, 결제는 계정 수준에서 처리합니다.

광고 기능을 사용하면 Whop 계정에서 외부 광고 네트워크의 광고를 구매할 수 있습니다. 광고 계정, 검토 및 게재 절차, 결제 관계는 모두 Whop이 소유합니다. 직접 관리하는 광고 계정을 연결하는 대신 API를 통해 캠페인을 생성합니다.

## 만들 수 있는 것

* 목표, 예산, 일정을 설정하여 **캠페인을 운영**합니다.
* 위치, 인구통계, 관심사, 기기, 언어로 **오디언스를 타기팅**하거나, 고객 목록을 [오디언스](https://docs.whop.com/ko/api-reference/audiences/audience)로 업로드합니다.
* 프롬프트로 AI 이미지나 동영상 **크리에이티브를 생성**하거나, 직접 에셋을 제공하거나, 연결된 외부 계정에 이미 있는 게시물을 홍보합니다.
* **기여 성과를 확인**합니다: 지출, 결과, 결과당 비용, 광고 지출 대비 수익을 모두 캠페인 객체에서 직접 확인할 수 있습니다.

## 타기팅할 수 없는 국가

Whop은 다음 국가를 타기팅하는 캠페인을 허용하지 않습니다:

| 국가 | 국가 코드 |
| - | - |
| 수단 | `SD` |
| 러시아 | `RU` |
| 쿠바 | `CU` |
| 이란 | `IR` |
| 북한 | `KP` |

광고 그룹을 생성하거나 타기팅 국가를 업데이트하는 요청에 이 코드 중 하나라도 포함되면 요청이 거부됩니다. 요청을 제출하기 전에 타기팅 위치에서 해당 코드를 제거하세요.

## 지출하기 전에

라이브 광고를 게재하려면 두 가지가 필요하며, 둘 다 한 번만 설정하면 됩니다:

* 대시보드에 연결된 **결제 수단**(Whop 잔액 또는 카드). 초안은 결제 수단 없이도 작동합니다.
* 목적지에 설치된 **Whop 픽셀**. 단, whop.com 스토어 페이지로 트래픽을 보내는 경우는 예외입니다. 외부 랜딩 페이지에는 먼저 [픽셀](https://docs.whop.com/ko/developer/ads/pixel.md)이 필요합니다.

[Ads API 개요](https://docs.whop.com/ko/api-reference/ads/overview.md)에서 각 항목에 대한 정확한 호출, 필요한 스코프, 항목이 누락되었을 때 받는 오류 문자열을 다룹니다.

## 핵심 객체

광고 캠페인, 광고 그룹, 광고, 오디언스. 각각은 [핵심 개념](https://docs.whop.com/ko/developer/concepts.md)에 정의되어 있습니다.

광고에는 하나의 계층 구조가 있으며, 모든 객체는 상위 수준에 속합니다.

**ad campaign** `adcamp_`

목표와 예산 전략을 보유합니다. [광고 캠페인](https://docs.whop.com/ko/api-reference/ad-campaigns/ad-campaign)을 참고하세요.

**ad group** `adgrp_`

타기팅, 최적화 목표, 일정, 그리고 기본적으로 자체 예산을 보유합니다. [광고 그룹](https://docs.whop.com/ko/api-reference/ad-groups/ad-group)을 참고하세요.

**ad** `ad_`

크리에이티브, 문구 변형, 클릭 유도 문구(CTA), 목적지 URL을 보유합니다. [광고](https://docs.whop.com/ko/api-reference/ads/ad)를 참고하세요.

[`POST /ads`](https://docs.whop.com/ko/api-reference/ads/create-an-ad)는 인라인 `ad_group`을 받고, 이 `ad_group`은 인라인 `ad_campaign`을 받으므로 한 번의 요청으로 단일 트랜잭션에서 전체 트리를 생성합니다. 이미 존재하는 광고 그룹에 광고를 연결하려면 대신 `ad_group_id`를 전달하세요.

지금이 아닌 나중에 게재하려면 인라인 `ad_campaign`의 `status`를 `draft`로 설정한 다음 [`PATCH /ad_campaigns/{id}`](https://docs.whop.com/ko/api-reference/ad-campaigns/update-an-ad-campaign)로 활성화하세요.

예산은 정확히 한 수준에만 존재하며, 두 곳 모두에 존재하지 않습니다: 기본적으로 광고 그룹에 있으며, `budget_optimization`을 `ad_campaign`으로 설정하면 캠페인에 있습니다.

## 결과 집계 방식

Whop이 보고하는 모든 성과 수치는 광고 네트워크가 아닌 **Whop 픽셀**에 의해 기여도가 산정됩니다.

`result_event`는 캠페인을 평가하는 기준이 되는 전환 이벤트의 이름이며, `results`는 픽셀 기여도로 산정된 해당 이벤트의 횟수입니다. `cost_per_result`는 지출을 이 횟수로 나눈 값입니다. 캠페인의 광고 그룹들이 서로 다른 목표에 최적화되어 있으면 단일 `result_event`가 없으므로 이 값은 `null`이 되고, `results`는 각 광고 그룹의 기여 결과 합계가 됩니다. Whop이 기여도를 산정할 수 있는 항목에 최적화하지 않는 경우, 두 값 모두 0이 아니라 `null`입니다.

## 목표 결과당 비용

캠페인의 `desired_cost_per_result`는 달성하고자 하는 결과당 비용(USD)입니다. 이는 목표일 뿐입니다: 비용 한도나 입찰 한도가 아니며, 캠페인 광고의 입찰 방식을 변경하지 않습니다. 캠페인을 운영하는 제휴사는 이를 목표로 삼을 결과당 비용으로 확인합니다. 광고 그룹 자체의 `desired_cost_per_result`는 다른 설정으로, 해당 광고 그룹의 비용 한도 또는 입찰 한도입니다. 목표를 지우려면 캠페인의 `desired_cost_per_result`를 `null`로 설정하세요.

## 광고 비용 결제

지출은 광고가 게재되면서 누적되고 이후에 청구됩니다. **결제는 계정의 모든 캠페인에 걸쳐 계정에 속합니다.** 각 수금 시 계정에 설정된 광고 결제 수단을 사용하여 적격한 미결제 캠페인 지출을 하나의 결제로 합산합니다. 캠페인마다 별도의 결제 수단을 설정하거나 별도의 재시도를 요청할 필요가 없습니다. 캠페인의 `spend` 필드는 `spend_currency`로 표시된, 사용자에게 청구된 금액입니다.

수금 시점은 누적 지출과 결제 임계값에 따라 달라집니다. 합산된다고 해서 하루에 한 번 결제된다는 의미는 아닙니다. AI 크리에이티브 생성은 별도의 잔액 결제를 사용합니다. 잔액이 부족하면 `deposit_url`을 포함한 `402`가 반환됩니다.

### 결제가 실패한 경우

계정 결제가 실패하면 청구 대상인 모든 캠페인의 게재가 차단됩니다. 영향을 받은 각 캠페인은 `delivery_status: "payment_failed"`를 보고하며, 설정된 `status`는 `active` 또는 `paused`로 유지됩니다. 캠페인 게재 가능 여부는 `delivery_status`를, 실패 이유는 `issues`를 확인하세요.

해결되지 않은 결제 실패가 있는 동안 계정은 캠페인을 활성화할 수 없습니다. 결제가 복구된 후에도 꺼진 상태로 유지하려면 여전히 캠페인을 일시 중지할 수 있습니다. Whop은 자동 재시도도 예약합니다. 결제 수단을 수정한 후 재시도를 요청할 수 있습니다.

### 결제 재시도

1. 계정의 Ads 대시보드에서 결제 실패 배너의 **Update payment method**를 선택하거나, Ads 설정을 열고 **Billing**을 선택하세요. 계정의 카드를 업데이트하거나 계정이 사용하는 잔액을 충전하세요.
2. 계정에 대해 **Retry payment**를 한 번 선택하세요. API 연동에서는 계정의 `biz_` ID와 `ad_campaign:update` 권한으로 [Retry Failed Ads Payments](https://docs.whop.com/ko/api-reference/accounts/retry-failed-ads-payments.md)를 호출해야 합니다.
3. 백그라운드 시도를 기다리세요. `queued: true`가 포함된 `202` 응답은 작업이 접수되었음을 확인할 뿐, **결제가 성공했음을 의미하지 않습니다**. 결과는 계정의 [광고 캠페인](https://docs.whop.com/ko/api-reference/ad-campaigns/list-ad-campaigns.md)에서 확인하세요.
4. 정산이 성공하면 결제 차단이 해제됩니다. 게재 상태가 다시 계산되고 동기화되는 동안 `processing`으로 표시될 수 있습니다. 활성으로 설정된 캠페인은 다른 게재 요건을 충족하면 재개될 수 있습니다. 일시 중지로 설정된 캠페인은 일시 중지 상태로 유지됩니다.

```bash theme={null}
curl -X POST "https://api.whop.com/api/v1/accounts/biz_YOUR_ACCOUNT/retry_ads_payment" \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Api-Version-Date: 2026-09-22"
```

```json theme={null}
{ "account_id": "biz_YOUR_ACCOUNT", "queued": true }
```

계정 재시도가 대기 중이거나 실행 중일 때 반복 요청하면 기다리라는 오류가 반환됩니다. 결제가 다시 실패하면 게재는 계속 차단됩니다: 다시 시도하기 전에 실패 이유를 확인하고 결제 수단을 수정하세요. 캠페인을 하나씩 반복하며 재시도하지 마세요. 이전 [캠페인 재시도 엔드포인트](https://docs.whop.com/ko/api-reference/ad-campaigns/retry-a-failed-ad-campaign-payment.md)는 `2026-09-22` 이전 API 버전에서는 여전히 계정 재시도를 대기열에 추가합니다. `2026-09-22`부터는 `410 Gone`을 반환합니다. 위의 계정 엔드포인트를 사용하세요.

설정된 `status`가 이미 `payment_failed`였던 이전 캠페인은 이전의 활성/일시 중지 설정이 보존되지 않았기 때문에 재시도가 성공하면 `paused`로 돌아갑니다.

## 캠페인이 게재되지 않는 이유

`delivery_status`가 이에 대한 직접적인 답을 제공합니다. 캠페인은 존재하지만 아무 일도 일어나지 않을 때 가장 먼저 확인해야 할 필드입니다. 여러 상태가 동시에 해당될 수 있으므로, 값은 이 순서에서 가장 높은 상태입니다:

| `delivery_status` | 의미 |
| - | - |
| `payment_failed` | 계정 결제가 실패했습니다. 설정된 활성/일시 중지 설정은 변경되지 않은 채 게재가 차단됩니다 |
| `all_ads_rejected` | 캠페인의 모든 광고가 거부되었습니다 |
| `draft` | 게재를 위해 제출되지 않았습니다 |
| `paused` | 캠페인 또는 그 안의 모든 광고 그룹을 일시 중지했거나, 남은 광고가 없습니다. 캠페인의 마지막 광고나 광고 그룹을 삭제하면 캠페인이 일시 중지됩니다 |
| `in_review` | 광고가 아직 콘텐츠 검토 중이며 아직 게재되는 것이 없습니다 |
| `learning` | 게재 중이며 아직 학습 기간입니다 |
| `processing` | 캠페인이 광고 네트워크에 도달하지 않았거나, 모든 광고 그룹이 아직 처리 중입니다 |
| `revise_content` | 캠페인이 실행을 기다리고 있으며, 콘텐츠 검토로 인해 대기 중인 모든 광고가 하나 이상의 광고 네트워크에서 제외되어 있습니다. 각 광고의 `content_review`를 확인하세요 |
| `issues` | 캠페인에 미해결 문제가 있거나, 모든 광고에 문제가 있습니다. `issues` 배열을 확인하세요 |
| `scheduled` | 캠페인 시작이 미래로 예정되어 있거나, 모든 광고 그룹이 자체 시작을 기다리고 있습니다 |
| `completed` | 캠페인 종료 시간이 지났습니다. 종료 시간이 없는 캠페인은 완료되지 않습니다 |
| `active` | 게재 중 |

광고와 광고 그룹은 서로 다른 값을 갖는 자체 `delivery_status`를 가집니다. 새 광고는 게재되기 전에 `in_review`를 거칩니다.

## 다음 단계

> [card] [광고 생성 및 게재](https://docs.whop.com/ko/api-reference/ads/overview.md)
>
> 크리에이티브부터 라이브 광고까지 전체 흐름을 두 번의 호출로 진행합니다.

> [card] [픽셀 설치](https://docs.whop.com/ko/developer/ads/pixel.md)
>
> 결과의 기여도를 산정하려면 먼저 필요합니다.

> [card] [오디언스 구축](https://docs.whop.com/ko/api-reference/audiences/create-audience.md)
>
> 타기팅하거나 제외할 고객 목록을 업로드합니다.

> [card] [Ads 레퍼런스](https://docs.whop.com/ko/api-reference/ad-campaigns/ad-campaign)
>
> 플레이그라운드가 포함된 모든 광고 엔드포인트.


## Related topics

- [광고](https://docs.whop.com/ko/elements/latest/ads/overview.md)
- [Shopify에 Whop 픽셀 설치하기](https://docs.whop.com/ko/developer/ads/platforms/shopify.md)
- [Kajabi에 Whop 픽셀 설치하기](https://docs.whop.com/ko/developer/ads/platforms/kajabi.md)
