> ## 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 Genel Bakış

> Bir kreatif oluşturup ardından kampanyayı, reklam grubunu ve reklamı tek bir istekte oluşturarak Whop Ads'i API üzerinden başlatın.

Whop Ads, ücretli reklamları doğrudan Whop hesabınızdan harici reklam ağlarında yayınlar. Reklam harcaması, hesabın tüm kampanyaları genelinde yapılandırılmış kartına veya bakiyesine faturalandırılır. Reklam hesabı, inceleme, başlatma ve faturalandırma işlemlerini Whop yürütür.

İki API çağrısı sizi sıfırdan yayında bir reklama götürür: bir kreatif oluşturun, ardından kampanyayı, reklam grubunu ve reklamı tek bir istekte oluşturun.

## Kaynaklar

| Kaynak | Amaç |
| - | - |
| [Ad Campaign](https://docs.whop.com/tr/api-reference/ad-campaigns/ad-campaign) | En üst düzey kapsayıcı: hedef ve (isteğe bağlı olarak) bütçe. |
| [Ad Group](https://docs.whop.com/tr/api-reference/ad-groups/ad-group) | Bir reklam kümesi için hedefleme ve bütçe. |
| [Ad](https://docs.whop.com/tr/api-reference/ads/ad) | Kreatif birim — metin, varlıklar, hedef URL. |
| [Audience](https://docs.whop.com/tr/api-reference/audiences/audience) | Reklam gruplarında hedeflenecek veya hariç tutulacak özel bir hedef kitle. |

## Faturalandırma ve ödeme kurtarma

Harcama, kampanyalar genelinde hesap düzeyinde tahsil edilir. Başarısız bir ödeme, her kampanyanın yapılandırılmış active/paused `status` değerini korurken yayını `delivery_status: "payment_failed"` ile engeller. Hesabın ödeme yöntemini düzeltin, ardından hesap için bir kez [Retry Failed Ads Payments](https://docs.whop.com/tr/api-reference/accounts/retry-failed-ads-payments.md) çağrısını yapın. Yanıt arka planda bir deneme kuyruğa alır; ödemeyi onaylamaz. Tahsilattan sonra, diğer yayın gereksinimlerine bağlı olarak aktif kampanyalar devam edebilir ve duraklatılmış kampanyalar duraklatılmış kalır.

Pano akışı, istek örneği, yinelenen istek davranışı ve eski kampanyaların ele alınması için [Reklamlar için ödeme](https://docs.whop.com/tr/developer/ads/overview.md#paying-for-ads) bölümüne bakın.

## Tek seferlik kurulum

* **Kapsamlar**: `media:generate`, `media:read`, `ad_campaign:create`, `ad_campaign:update`, `ad_campaign:basic:read`.
* **Reklam ödeme yöntemi**: panoda bağlanır (bakiye veya kart). Yalnızca başlatma için gereklidir — taslaklar onsuz çalışır.

**1. Bir kreatif oluşturun**

```bash theme={null}
curl -X POST "https://api.whop.com/api/v1/media/generate" \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "image", "prompt": "A running club jogging across a bridge at sunrise, warm light, joyful energy"}'
```

Bakiyenizden faturalandırılır (`amount_charged`; yetersiz bakiye → `deposit_url` ile birlikte `402`). `status` `ready` olana kadar [`GET /media/{id}`](https://docs.whop.com/tr/api-reference/media/retrieve-media-asset) uç noktasını yoklayın, ardından `file.id` değerini kullanın:

```json theme={null}
{
	"id": "media_Hx7qg4tZc97o",
	"status": "ready",
	"file": { "id": "file_Zsv4DYkrbWE7h" }
}
```

`failed` ücreti iade eder — istemi düzenleyip yeniden deneyin. Video: `"type": "video"` ile birlikte isteğe bağlı `duration_seconds` (5/10/15), `resolution` (`480p`–`4k`) ve en fazla 4 `reference_media` dosya kimliği (ilki açılış karesinin temelini oluşturur).

**2. Reklamı oluşturun ve başlatın — tek istek**

Satır içi bir `ad_group` ve `ad_campaign` ile [`POST /ads`](https://docs.whop.com/tr/api-reference/ads/create-an-ad), tüm ağacı tek bir işlemde oluşturur ve başlatır:

```bash theme={null}
curl -X POST "https://api.whop.com/api/v1/ads" \
  -H "Authorization: Bearer $WHOP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Run club launch ad",
    "primary_texts": ["Join 10,000 runners chasing their next PR together."],
    "headlines": ["Find your stride"],
    "call_to_action": "sign_up",
    "url": "https://whop.com/your-store-page",
    "creatives": [{"id": "file_Zsv4DYkrbWE7h"}],
    "ad_group": {
      "title": "US broad",
      "budget_amount": 25,
      "budget_type": "daily",
      "regions": {"include": {"countries": ["US"]}},
      "ad_campaign": {"title": "Run club growth", "objective": "sales"}
    }
  }'
```

Harcamaya hazır değil misiniz? `ad_campaign`'e `"status": "draft"` ekleyin, ardından daha sonra [`PATCH /ad_campaigns/{id}`](https://docs.whop.com/tr/api-reference/ad-campaigns/update-an-ad-campaign) `{"status": "active"}` ile başlatın.

| Alan | Kural |
| - | - |
| `creatives` | `format` içermeyen bir giriş zorunludur (temel varlık). `square` / `vertical` / `horizontal` bunun üzerine isteğe bağlı kırpmalardır. |
| `url` | Web sitesi reklamları için zorunludur. whop.com mağaza sayfanız olduğu gibi çalışır; harici bir sayfa için [Whop pikselinizin](https://docs.whop.com/tr/developer/ads/pixel.md) yüklü olması gerekir. |
| Bütçe | Bütçe tek bir düzeye aittir: reklam grubunda `budget_amount` (varsayılan) veya `budget_optimization: "ad_campaign"` ile kampanyada — asla ikisi birden değil. |
| Para birimi | `budget_amount` USD cinsindendir; bütçeler bu para biriminde saklanır ve faturalandırılır. Bunun yerine bir bütçeyi hesabın `ads_reporting_currency` cinsinden belirtmek için `budget_amount_local` gönderin; Whop bunu güncel kurdan dönüştürür ve USD sonucunu saklar. Birini veya diğerini gönderin, asla ikisini birden değil. Yanıtlar `budget_amount`, `budget_amount_local` ve `budget_currency` içerir. |
| Hedefleme | Otomatik optimizasyon için `demographics` / `devices` alanlarını atlayın. `regions` ISO 3166 kullanır (`"US"`, `"US-CA"`). |

Mevcut kapsayıcıları yeniden kullanmak için `ad_group` yerine `ad_group_id` veya `ad_campaign` yerine `ad_campaign_id` iletin.

**3. İzleyin**

[`GET /ads/{id}`](https://docs.whop.com/tr/api-reference/ads/retrieve-an-ad) uç noktasını yoklayın: `delivery_status` canlı durumdur (içerik denetimi için kısa bir `in_review` normaldir) ve `issues[]`, reklam ağının eşzamansız olarak reddettiği her şey için insan tarafından okunabilir bir `message` içerir.

Yayını reklamlar, reklam grupları veya kampanyalar üzerinde [`pause`](https://docs.whop.com/tr/api-reference/ads/pause-an-ad) / [`unpause`](https://docs.whop.com/tr/api-reference/ads/unpause-an-ad) ile kontrol edin. Metni veya kreatifleri [`PATCH /ads/{id}`](https://docs.whop.com/tr/api-reference/ads/update-an-ad) ile düzenleyin — `creatives` göndermek tüm kümeyi değiştirir, bu nedenle temel girişi de ekleyin.

## Hatalar

Her kontrol, mesajı neyin düzeltilmesi gerektiğini söyleyen bir `400` hatasıdır:

| Hata şunu içerir | Çözüm |
| - | - |
| `The Whop pixel was not detected on <url>` | Kendi whop.com mağaza sayfanızı kullanın veya açılış sayfasına [pikseli yükleyin](https://docs.whop.com/tr/developer/ads/pixel.md). |
| `Connect an ads payment method before launching` | `ad_campaign.status: "draft"` ile oluşturun, kullanıcının panoda bir ödeme yöntemi bağlamasını sağlayın, ardından `PATCH` ile `active` yapın. |
| `Include a base creative` | `format` içermeyen bir `creatives` girişi ekleyin. |
| `A destination URL is required` | `url` iletin. |
| `budget_amount is required` / `can't be set` | Bütçeyi doğru düzeye taşıyın (yukarıdaki alan kurallarına bakın). |
| `Provide either budget_amount (USD) or budget_amount_local` | İki alan farklı bütçeler belirtti; birini gönderin. Yerel tutarı saklanan tutarı yeniden ifade eden, geri gönderilmiş bir `GET` gövdesi sorun değildir. |
| `503` `Exchange rate for <currency> is unavailable` | Whop'un şu anda hesabın raporlama para birimi için güncel bir kuru yok; birkaç dakika içinde yeniden deneyin. |
| `402` + `deposit_url` (media) | Bakiye yüklemesi için kullanıcıyı `deposit_url` adresine yönlendirin, ardından yeniden deneyin. |


## Related topics

- [Whop API'ye Genel Bakış](https://docs.whop.com/tr/api-reference/overview.md)
- [Ads API](https://docs.whop.com/tr/api-reference/ads/ad.md)
- [Whop API temel kavramları](https://docs.whop.com/tr/developer/concepts.md)
