Skip to main content
Fatura, tek bir müşteriye hitaben, bir veya daha fazla varyantınız için düzenlenen numaralı bir hesap belgesidir. Varyant, genellikle bir ürün için sattığınız fiyat ve faturalandırma kurulumudur. Kimliği plan_ ile başlar ve fatura kalemleri bunu plan_id olarak alır. Müşteri ödeme yapmadan önce onunla bir fiyat üzerinde anlaştığınızda faturayı kullanın; örneğin bir teklif, bir hizmet veya bir kurumsal sipariş için. Doğru olana kadar bir taslak oluşturursunuz, ardından toplamları kilitlemek ve ödemeye açmak için onu düzenlersiniz (issue). Göndermek (send) bunu yapar ve faturayı tek bir çağrıyla e-postayla iletir. Kod yazmadan panonuzdan fatura göndermek için Fatura oluşturma ve gönderme sayfasına bakın.
Bu sayfadaki faturalar her istekte Api-Version-Date: 2026-10-24 veya daha yeni bir sürüm gerektirir. Daha eski bir sürüm içeren istekler, farklı çalışan eski fatura API’sine ulaşır. Bkz. Başlamadan önce.

Bir fatura nasıl çalışır

Yerel bir fatura bir ödemedir. Kimliği pay_ ile başlar ve müşteri ödeme yaptıktan sonra da aynı kalır; böylece onu Retrieve Payment ile de okuyabilirsiniz. Her fatura ayrıca hesabınızın kendi sırasındaki bir sonraki numarayı alır; örneğin #00000042 veya hesabınızın bir fatura öneki varsa #ACME-00000042.
  1. Kalemler, bir müşteri ve faturalandırma ayrıntılarıyla bir taslak oluşturursunuz. Taslak hiçbir ücret tahsil etmez ve kimseye e-posta göndermez.
  2. Faturayı düzenlersiniz veya gönderirsiniz. Düzenleme, nihai vergiyi hesaplar ve faturayı ödemeye açar. Gönderme ise faturayı düzenler ve hemen ya da planladığınız bir zamanda e-postayla iletir.
  3. Müşteri öder. Faturayı düzenlediğinizde veya gönderdiğinizde Whop müşterinin kayıtlı ödeme yönteminden tahsilat yapar ya da müşteri Whop’un barındırılan ödeme sayfası üzerinden öder.
  4. Siparişi payment.succeeded webhook’undan karşılarsınız.
Faturalar, bekleme listesi yerine release_method: buy_now olan, yani hemen satın alınabilen varyantları faturalandırır. Tek seferlik bir varyant bir kez faturalandırılır; yinelenen bir varyant ise fatura ödendiğinde bir abonelik başlatır. Belirli sayıda ödemeden sonra durdurmayı da kapsayan Bir aboneliği faturalandırma bölümüne bakın.

Başlamadan önce

API sürümünü gönderin

/invoices iki farklı API sunar ve isteğinizin çözümlendiği Api-Version-Date hangisinin yanıt vereceğini belirler. Düzenleme, gönderme, planlanmış bir gönderimi iptal etme ve PDF oluşturma yalnızca yerel API’de bulunur; bu nedenle hangi sürümü gönderirseniz gönderin yerel faturalara ulaşır. GET /invoices ve POST /invoices/{id}/void gibi her iki API’de de bulunan yollar sürümü izler. Bir anahtarın sabitlemesine güvenmek yerine başlığı her istekte gönderin; böylece anahtar değiştirmek sizi asla iki API arasında taşımaz. API sürümleri sabitlemeleri ve değişiklik günlüğünü açıklar. Yerel API eski inv_ faturalarını listelemez veya getirmez, eski API de yerel faturaları döndürmez.

API’yi çağırın

Bu sayfadaki örnekler API’yi, her istekte sürüm başlığını gönderen küçük bir yardımcı aracılığıyla çağırır.
Bir yeniden denemenin asla ikinci bir fatura oluşturmaması veya bir işlemi tekrarlamaması için her POST isteğinde bir Idempotency-Key gönderin. Generate Invoice PDF bunun istisnasıdır: her çağrı yeni bir dosya oluşturur, bu yüzden yanıtları yeniden oynatmaz.

Bir taslak oluşturun

Create Invoice, POST /invoices ile bir taslak kaydeder.
Yanıt, taslakla birlikte 201 Created olur. Taslak oluşturmak ücret tahsil etmez, e-posta göndermez ve webhook göndermez. Bu yanıt alanların bir alt kümesini gösterir:
account_id, faturayı düzenleyen hesaptır ve biz_ önekine sahiptir. Bir hesap API anahtarı, kendi hesabını kullanmak için bunu atlayabilir. Create Invoice tüm istek ve yanıt alanlarını listeler. Bir taslak, numarasını oluşturulduğu anda kullanır; bu nedenle attığınız bir taslak sıranızda bir boşluk bırakır. Bir taslağı atmak için onu silin. Listenizde tutmak için bunun yerine geçersiz kılın.

Kalem ekleyin

items 1 ile 50 arasında kalem alır. Her kalem, mevcut bir varyant için plan_id ya da satır içinde bir varyant bulmak veya oluşturmak için plan alır; ayrıca isteğe bağlı bir quantity de alır. Satır içi bir plan, Create Payment ile aynı bul-veya-oluştur girdisini kullanır; örneğin { "plan": { "product_id": "prod_xxxxxxxxxxxxx", "plan_type": "one_time", "initial_price": 250, "currency": "usd" } }. Bunun için plan:create gerekir; satır içi bir product ise ayrıca ürün iznini, yani access_pass:create veya access_pass:update iznini gerektirir. Oluşturma ve güncelleme işlemleri şu kuralları ihlal eden kalemleri reddeder:
  • Her kalem, hesabınıza ait hemen satın alınabilen bir varyanttır. Bir varyant yalnızca bir kez yer alır; daha fazla birim için quantity kullanın.
  • Hiçbir varyant arşivlenmiş değildir ve bir taslağı düzenlemek veya göndermek bunu yeniden kontrol eder; bu nedenle varyantı arşivden çıkarın veya başka bir varyant seçin.
  • quantity 1 ile 999.999 arasındadır ve yalnızca birden fazla miktara izin veren bir varyant için 1’in üzerindedir. Yinelenen varyantlar buna izin vermez, bu yüzden yinelenen bir kalemin miktarı 1’dir.
  • Yinelenen bir varyant bir ürüne ait olmalıdır.
  • Her kalem aynı para birimini kullanır.
  • Birden fazla kalem içeren bir faturada, ürünü olan her kalem bir uygulama değil, normal bir ürün (standart ürün türü) olmalıdır. Yinelenen kalemler tek bir faturalandırma dönemini, ücretsiz deneme süresini ve split_pay_required_payments değerini paylaşır; tüm kalemlerin uyumlu ödeme, vergi ve erişim ayarlarına sahip olması gerekir. Özel alanlara veya parolaya sahip varyantlar birleştirilemez. Özel bir ücret gibi ürünü olmayan kalemler diğerlerinin yanında yer alabilir.
Yanıttaki her satır kaleminin bir label değeri vardır; bu ürünün başlığıdır veya ürünü olmayan bir varyant için varyantın başlığıdır. E-posta, PDF ve ödeme sayfası bunu gösterir. Taslak, kalemlerini kaydettiğiniz andaki her varyantın fiyatını korur; böylece varyantta sonradan yapılan bir fiyat değişikliği faturayı etkilemez. Tek seferlik bir kalem kendi fiyatından faturalandırılır. 2026-11-11 API sürümünden itibaren, yinelenen bir kalem oluşturmak veya değiştirmek, ilk faturaya kalemin initial_price ve renewal_price toplamını dahil eder. Daha eski sürüm sabitlemeleri yalnızca yenileme fiyatını kullanır. items alanını atlayan düzenlemeler kayıtlı fiyatları korur.

Müşteriyi ve faturalandırma ayrıntılarını ayarlayın

member_id veya email_address ile billing_address veya mailing_address_id gönderin; bir çiftin ikisini birden asla göndermeyin. Faturalandırma adresi bir müşteri gerektirir. Müşteri taslakta isteğe bağlıdır ancak düzenlemek için zorunludur. Whop, faturayı düzenlediğinizde müşterinin konumunu belirlemek için faturalandırma adresini kullanarak vergiyi hesaplar. Vergi uygulandığında ve Whop müşterinin nerede olduğunu belirleyemediğinde düzenleme reddedilir; bu nedenle vergi tahsil ettiğiniz her durumda bir faturalandırma adresi ekleyin.

Bir taslağı düzenleyin

Update Invoice, PATCH /invoices/{id} ile bir taslağı değiştirir. Yalnızca değiştirdiğiniz alanları gönderin.
  • items tüm listeyi değiştirir ve her varyantın güncel fiyatını okur. Kayıtlı kalemleri ve fiyatları korumak için bunu atlayın.
  • member_id değiştirmek, yenilerini göndermediğiniz sürece kayıtlı faturalandırma adresini ve ödeme yöntemini kaldırır. recipient_emails korunur; bu yüzden yeni bir liste de gönderin, aksi halde önceki müşteri fatura e-postasını almaya devam eder.
  • email_address ve customer_name kabul edilmez. Başka birini faturalandırmak için farklı bir member_id gönderin.
  • Planlanmış gönderimi olan bir taslak, gönderimi iptal edene kadar yalnızca recipient_emails değişikliğini kabul eder.
  • Fatura düzenlendikten sonra yapabileceğiniz tek değişiklik, tek başına gönderilen recipient_emails değişikliğidir ve bu yalnızca fatura open veya uncollectible durumundayken mümkündür. Diğer tüm düzenlemeler 400 ile reddedilir.

Müşterinin nasıl ödeyeceğini seçin

Düzenlenmiş bir fatura için ödeme almanın iki yolu vardır. Kayıtlı ödeme yöntemi taslağa eklendiğinden, faturayı düzenlemeden önce birini seçin. Düzenlenmiş bir fatura, kayıtlı bir ödeme yöntemi olsa bile bir checkout_link alır. Otomatik tahsilat başarısız olursa müşteri yine de ödeme sayfası üzerinden ödeyebilir.

Kayıtlı bir ödeme yönteminden tahsilat yapın

payment_method_id ile taslağa kayıtlı bir ödeme yöntemi ekleyin. Bu, müşterinin kayıtlı yöntemlerinden biri olmalıdır. Ödeme yöntemlerini kaydetme bir müşterinin yöntemi nasıl kaydettiğini gösterir; List payment methods ise bir üyenin sahip olduğu yöntemleri bulur. Faturayı düzenlediğinizde veya gönderdiğinizde ve toplamı sıfırın üzerinde olduğunda Whop şunları yapar:
  1. Create Payment işleminin kayıtlı bir ödeme yönteminde çalıştırdığı kontrollerin aynısını çalıştırır.
  2. Faturalandırılan miktarlar için stok ayırır ve ödemenin ücretlerini hazırlar.
  3. Faturayı open olarak döndürür ve yöntemden oturum dışı tahsilat yapar. Tahsilat, Issue Invoice veya Send Invoice çağrısına ilettiğiniz charge_at zamanında; aksi halde hâlâ ilerideyse due_at zamanında; aksi halde hemen gerçekleşir. scheduled_charge_at henüz gerçekleşmemiş bir tahsilatı gösterir.
Yanıt, tahsilatın başarılı olup olmadığını söylemez. Siparişi faturanın pay_ kimliği için gelen payment.succeeded webhook’undan karşılayın. Ödenmiş bir fatura üyeliği tamamlar ve metadata değerleriniz tahsilatta ve üyelikte bulunur. Fatura ödemelerinde ödeme kuralları, ödeme kurallarınızın tahsilatı nasıl denetlediğini açıklar.

Otomatik tahsilat reddedilirse

Reddedilen bir tahsilat faturayı open durumunda bırakır ve ayrılan stoku geri verir. Son denemenin neden başarısız olduğunu öğrenmek için faturayı bir ödeme olarak getirin ve failure_message değerini okuyun. Tahsilat reddedildiğinde veya müşterinin işlem yapmasını gerektirdiğinde Whop, müşterinin bunun yerine ödeme sayfası üzerinden ödeyebilmesi için faturanın ödeme bağlantısını alıcılarına e-postayla gönderir. Bu, göndermeden düzenlediğiniz bir fatura için Whop’un gönderdiği tek e-postadır. Bir checkout_link ve recipient_emails içinde en az bir giriş gerektirir ve gönderim sınırına dahil edilmez.
Oturum dışı bir tahsilat müşteriye 3D Secure doğrulaması gösteremez. Müşterinin bankası bunu isterse otomatik tahsilat tamamlanmaz ve fatura, müşteri kimliğini doğrulayana veya başka bir yolla ödeyene kadar ödenmemiş kalır.

Faturayı düzenleyin

Issue Invoice bir taslağı açık bir faturaya dönüştürür. Whop faturayı yeniden kontrol eder, nihai vergiyi hesaplar ve status değerini open, totals_status değerini final olarak ayarlar. Faturanın kayıtlı bir ödeme yöntemi ve sıfırın üzerinde bir toplamı varsa Whop ardından Kayıtlı bir ödeme yönteminden tahsilat yapın bölümünde açıklandığı gibi tahsilat yapar.
  • Vergi kesinleşir. tax_amount bir taslakta null olur ve faturayı düzenlediğinizde ayarlanır. total ve amount_due bunu içerir.
  • Fatura bir ürünü faturalandırdığında Whop müşterinin üyeliğini oluşturur. Üyelik, fatura ödenene kadar erişim olmadan taslak durumunda kalır. Tüm kalemlerinin ürünü olmayan bir fatura üyelik almaz.
  • payment.created olayı, faturanın pay_ kimliği için bir kez tetiklenir.
  • Yeniden düzenlemek güvenlidir. Zaten open olan bir faturayı düzenlemek aynı kontrolleri yeniden çalıştırır ve geçerlerse faturayı değiştirmeden döndürür: toplamları aynı kalır ve hiçbir şey yeniden tahsil edilmez.
  • Düzenleme faturayı e-postayla göndermez; reddedilen bir tahsilattan sonraki ödeme bağlantısı bunun istisnasıdır. Faturayı e-postayla iletmek için bunun yerine gönderin veya ödeme bağlantısını kendiniz iletin.
Reddedilen bir düzenleme hiçbir şeyi değiştirmez ve hiçbir şey tahsil etmez. Nedeni düzeltin ve faturayı yeniden düzenleyin. Düzenleme hataları nedenleri listeler. Düzenlenmiş, open durumundaki bir fatura, pay_xxxxxxxxxxxxx.<signature> biçiminde imzalı bir değer olan bir checkout_link taşır. Bu, faturayı sabit fiyatıyla Whop’un barındırılan ödeme sayfasında açar.
1

Bağlantıyı düzenlenmiş faturadan okuyun

checkout_link, fatura open olmadığı sürece null olur; bu nedenle taslaklarda ve ödenmiş, geçersiz kılınmış veya tahsil edilemez faturalarda bulunmaz. Bir kurumsal alıcıya faturalandırılan, üyeliği iptal edilmiş bir faturada ve kimlik bilginizde payment:charge izni olmadığında da null olur. Kurumsal alıcı, bir kişi değil başka bir Whop hesabı olan müşteridir.
2

Barındırılan ödeme sayfası URL'sini oluşturun

Bağlantıyı ilk . karakterinden bölün: faturanın pay_ kimliği bundan önce, token ise sonra gelir.
3

Müşteriye gönderin

Whop’un bağlantıyı e-postayla göndermesi için faturayı gönderin veya URL’yi kendi e-postanıza ya da fatura sayfanıza ekleyin. Bu bağlantı üzerinden yalnızca faturanın müşterisi ödeme yapabilir. Diğer herkes reddedilir ve faturanın müşterisi olarak oturum açması istenir. Bağlantı, fatura ödendiğinde, geçersiz kılındığında veya tahsil edilemez olarak işaretlendiğinde çalışmayı durdurur.
4

Siparişi webhook'tan karşılayın

Otomatik tahsilatta olduğu gibi faturanın pay_ kimliği için payment.succeeded olayını dinleyin. Webhook’lar bir işleyici gösterir.
Ödeme sayfası, faturanın numarasını ve vade tarihini kalemlerinin yanında gösterir; vade tarihi geçtiğinde kırmızıya döner. Müşteri faturadaki kalemleri ve toplamı öder ve promosyon kodu ekleyemez.

Gönderme, planlama ve hatırlatma

Send Invoice, POST /invoices/{id}/send ile bir faturayı e-postayla gönderir. Bir taslağı göndermek, Issue Invoice ile aynı şekilde önce onu düzenler. open durumundaki bir faturayı göndermek onu yeniden e-postayla iletir.
E-posta, hesabınızın adını ve logosunu, fatura numarasını, toplamı, vade tarihini, her kalemi ve faturanın ödeme sayfasını açan bir düğmeyi gösterir. Whop yalnızca müşterinin e-postadan ödeyebileceği bir faturayı e-postayla gönderir. open durumundaki bir faturanın gönderilmesi için bir checkout_link gerekir; bir taslak ise kurumsal alıcı olmayan bir müşteri gerektirir. Kurumsal bir alıcıya faturalandırılan bir taslak, kayıtlı bir ödeme yöntemi varsa yine de gönderilebilir, çünkü bunun yerine tahsilat yapılır.

E-postayı kimler alır

Her gönderim, her adrese ayrı bir e-posta olarak bir kez gönderilir; böylece alıcılar birbirlerinin adreslerini asla görmez. Adresler şunlardır:
  • Müşterinin Whop hesabındaki e-posta; fatura PDF’i bunu Bill to altında yazdırır.
  • recipient_emails içindeki her giriş.
Whop recipient_emails değerini küçük harflerle kaydeder ve listedeki tekrarları kaldırır; böylece her ikisinde de bulunan bir adres tek bir e-posta alır. Boş bir recipient_emails, Whop’un müşteri dahil kimseye e-posta göndermeyeceği anlamına gelir. Whop’un bir faturayı e-postayla göndermesini engellemek için bunu kullanın:
  • Send Invoice, bunun yerine kayıtlı bir ödeme yönteminden tahsilat yapmadığı sürece faturayı reddeder.
  • Reddedilen bir tahsilattan sonra ödeme bağlantısı gönderilmez.
  • Hatırlatma gönderilmez. open durumundaki bir faturada recipient_emails değerini temizlemek kalan hatırlatmaları durdurur.

Whop e-posta yerine ne zaman tahsilat yapar

payment_method_id içeren ve toplamı sıfırın üzerinde olan bir taslak, tıpkı düzenlediğinizde olduğu gibi e-postayla gönderilmek yerine tahsil edilir. Otomatik tahsilat reddedilirse bölümü, tahsilat başarısız olduğunda ne olacağını açıklar. Böyle bir taslak boş bir recipient_emails ile gönderilebilir, çünkü kimsenin e-postaya ihtiyacı yoktur.

Gönderim sınırı

Her fatura, onu düzenleyen gönderim dahil 24 saat içinde üç kez e-postayla gönderilebilir. Bu süre içindeki dördüncü bir gönderim, error.code değeri invoice_send_limit_reached olan bir 429 ile reddedilir. Hatırlatmalar, reddedilen bir tahsilattan sonraki ödeme bağlantısı ve e-posta yerine tahsilat yapan bir gönderim bu sınıra dahil edilmez.

Bir gönderimi planlayın

Bir taslağı bunun yerine daha sonra göndermek için send_at iletin. Taslak taslak olarak kalır ve zamanı scheduled_send_at içinde gösterir. O zaman geldiğinde Whop, Send Invoice’ı o anda çağırmışsınız gibi faturayı gönderir.
  • Yalnızca bir taslak planlanabilir ve send_at gelecekte olmalıdır. Whop, planladığınızda alıcıları ve ödeme bağlantısını hemen gönderimde olduğu gibi kontrol eder.
  • Zamanı değiştirmek için yeni bir send_at ile yeniden gönderin.
  • Gönderim gerçekleşene veya siz iptal edene kadar düzenleme kilitlidir. Yalnızca recipient_emails değerini değiştiren bir güncelleme yine de çalışır, ancak tahsil edilmeyecek bir taslaktan son alıcıyı kaldıramaz.
  • POST /invoices/{id}/unschedule ile Cancel Scheduled Send. scheduled_send_at yeniden null olur ve taslak tekrar düzenlenebilir. Planlanmış gönderimi olmayan bir faturayı iptal etmek onu değiştirmeden döndürür.
  • Planlanmış bir taslağı geçersiz kılmak planlanmış gönderimini durdurur.
Whop vadesi gelen gönderimleri her dakika kontrol eder; bu nedenle planlanmış bir gönderim send_at zamanından yaklaşık bir dakika içinde gerçekleşir. Örneğin planladığınızdan bu yana bir varyant silindiği için reddedilirse fatura taslak olarak kalır, scheduled_send_at yeniden null olur ve API nedeni döndürmez. Diğer tüm hatalar yaklaşık her 10 dakikada bir, toplamda en fazla 12 deneme olacak şekilde yeniden denenir. Bir deneme başarılı olana veya Whop yeniden denemeyi bırakana kadar scheduled_send_at, null yerine bir sonraki denemenin zamanını gösterir. Faturanın open olduğunu doğrulamak için send_at zamanından sonra faturayı okuyun.

Hatırlatmalar

Send Invoice, due_at değerine sahip bir faturayı e-postayla gönderdiğinde Whop ayrıca due_at tarihinden 1, 3, 7, 14, 30 ve 60 gün sonrası için hatırlatmalar planlar; tarihi geçmiş olanları atlar. Her hatırlatma faturayla aynı adreslere gider ve faturanın vadesinin kaç gün geçtiğini belirtir. Hatırlatmalar yalnızca fatura open durumundayken gönderilir; bu nedenle fatura ödendiğinde, geçersiz kılındığında veya tahsil edilemez olarak işaretlendiğinde durur. Bir ödeme devam ederken vadesi gelen bir hatırlatma, ödeme tamamlanana kadar bekler. Göndermeden düzenlediğiniz veya e-posta yerine tahsil edilen bir fatura hatırlatma almaz.

E-posta geçmişi

List Invoice Sends, GET /invoices/{id}/sends ile kaydedilmiş e-posta gruplarını en yeniden başlayarak döndürür. İlk ve tekrar e-postalarını, planlanmış e-postaları, hatırlatmaları ve kayıtlı bir ödeme yöntemine yapılan başarısız bir tahsilattan sonraki ödeme takiplerini içerir. En son kaydedilen gönderim için ilk girişi kullanın; daha eski girişleri okumak için page_info.end_cursor değerini after olarak kullanın. Manuel gruplar, faturanın daha önce tamamlanmış bir e-posta geçmişi yoksa send, aksi halde resend kullanır. Tür, tamamlanan grup kaydedildiğinde seçilir; bu nedenle birlikte kuyruğa alınan istekler tamamlanma sırasına göre sınıflandırılır. Daha önceki kaydedilmemiş e-postalar bilinmez olarak kalır. Her giriş kind, sent_at, recipient_count, recipients ve actor alanlarını içerir. Geçmişi okumak payment:basic:read gerektirir. Adresler ayrıca member:email:read gerektirir; bu izin yoksa recipients boştur. Göndereni görmek ayrıca company:authorized_user:read gerektirir; aksi halde actor null olur. Otomatik gönderimlerde ve hesap API anahtarlarında da actor null olur. Çalışan süreç, grubun tamamını teslimata gönderdikten sonra bir giriş ekler. Kısmi bir grup için, yalnızca bir yeniden deneme grubu tamamlarsa giriş ekler. Giriş, orijinal alıcı listesini korur. Kaydedilmiş bir grup, gelen kutusuna teslimatı doğrulamaz. E-posta gönderici, fatura veya alıcılar teslimattan önce değişirse mesajları engelleyebilir. Geçmiş, bu özellik kullanıma sunulmadan önce gönderilen e-postaları içermez. Bir faturayı e-posta göndermeden düzenlemek geçmişe giriş eklemez.

Bir PDF indirin

Generate Invoice PDF faturayı PDF olarak oluşturur ve ona kısa ömürlü bir bağlantı döndürür. payment:basic:read gerektirir ve her durumda çalışır.
Yanıtta url ve expires_at bulunur. Bağlantı 15 dakika çalışır ve ona sahip olan herkes dosyayı indirebilir. Süresi dolduğunda yeni bir bağlantı oluşturun. PDF işletmenizle başlar: sayfanın başında hesabınızın adı yer alır ve alt bilgi, faturanın Whop Inc tarafından sizin adınıza ve sizin namınıza düzenlendiğini belirtir. Fatura numarasını, tarihini ve vade tarihini ve Bill to ayrıntılarını gösterir. Her kalem miktarını, birim fiyatını ve tutarını gösterir; ardından ara toplam, hizmet ücreti, vergi ve ödenecek tutar gelir. Yinelenen bir kalem içeren bir fatura ayrıca yenileme tutarını ve ne sıklıkla yenilendiğini belirtir. Bir taslağın PDF’i tahmini toplamlarını gösterir; vergi, faturayı düzenleyene kadar sıfırdır. Bazı içerikler kimlik bilginizin izinlerine bağlıdır:

Bir aboneliği faturalandırın

Müşteri faturayı ödediğinde bir abonelik başlatmak için faturaya yinelenen bir varyant ekleyin. Whop ardından aboneliği her faturalandırma döneminde bir kez yeniler.
  1. Fatura ilk dönemi ve varsa peşin ücreti faturalandırır. Yinelenen bir kalem bir ürüne ait olmalıdır ve miktarı 1’dir. 2026-11-11 API sürümünden itibaren ilk faturası initial_price ile renewal_price toplamını faturalandırır. Varyantın ücretsiz bir denemesi yoksa ödeme, ilk ücretli faturalandırma dönemini hemen başlatır. Varsa abonelik denemeyle başlar. Panoda, özel bir yinelenen kalemin isteğe bağlı bir Upfront fee alanı vardır. Satır kaleminin initial_price değeri unit_amount içindeki bu tek seferlik kısmı belirtir; fatura sayfası, e-posta ve PDF bunu kendi Upfront fee satırında listeler.
  2. Whop kayıtlı ödeme yönteminden düzenleme sırasında tahsilat yapsa da müşteri checkout_link üzerinden ödese de faturanın ödenmesi aboneliği başlatır. İlk dönem ödemeyle başlar. Bağlantıdan açılan ödeme sayfası, faturanın alıcı ücreti dahil yenileme tutarını ve ne sıklıkla yenilendiğini belirtir.
  3. Her yenileme, faturayı düzenlerken veya gönderirken seçtiğiniz şekilde tahsil edilir. Yalnızca yinelenen kalemleri, faturanın alıcı ücretiyle birlikte, her varyantın faturayı düzenlediğiniz andaki yenileme fiyatından faturalandırır. Kalemleri kaydettikten sonra varyantın fiyatı değiştiyse bu, taslakta kayıtlı fiyattan farklı olabilir. Tek seferlik kalemler bir kez faturalandırılır.
Yenilemelerin nasıl tahsil edileceğini seçmek için Issue Invoice veya Send Invoice çağrısına collection_method iletin. Planlanmış bir gönderim, planlarken kullandığınız collection_method değerini uygular; taslak bunu scheduled_collection_method olarak gösterir. send_invoice en az bir recipient_emails adresi gerektirir ve bir işletmeye faturalandırılan faturalar için kullanılamaz. Uygulandığı sürece faturanın son alıcısı kaldırılamaz. Yinelenen kalemi olmayan bir fatura collection_method değerini reddeder. İlk faturayı kartla ödemek send_invoice ayarını korur. Her yenileme kendi pay_ kimliği ve payment.* webhook’larıyla ayrı bir ödemedir. charge_automatically yenilemesi numaralı bir fatura değildir, bu nedenle List Invoices içinde görünmez. send_invoice yenilemesi List Invoices içinde numaralı bir faturadır ve Whop bunu otomatik olarak tahsil etmez. Abonelik, müşteri faturanın checkout_link bağlantısı üzerinden ödeyene kadar past_due durumunda kalır. Müşteri bu süre zarfında erişimini korur. Yenilemeleri durdurmak için üyeliği iptal edin. Üyelik iptal edildiğinde açık bir yenileme faturasının checkout_link bağlantısı çalışmayı durdurur. Aboneliği bulmak için faturayı bir ödeme olarak getirin ve member:basic:read gerektiren membership_id değerini okuyun.

Ücretsiz bir denemeyle başlayın

Bir fatura, ödeme sayfasında olduğu gibi yinelenen bir varyantın trial_period_days değerine uyar. İlk fatura yalnızca varyantın initial_price değerini faturalandırır. Ödenmesi denemeyi başlatır ve ilk yenileme, deneme bittiğinde renewal_price değerini faturalandırır. 2026-11-16 17:00 UTC’den önce oluşturulan faturalar ilk dönemi faturalandırır ve denemeyi atlar.
  • Varyanta daha önce aboneliği olan bir müşteri deneme almaz. İlk faturası initial_price ile renewal_price toplamını faturalandırır. Yenileme faturaları hiçbir zaman deneme başlatmaz.
  • Deneme varyanttan gelir. Özel bir yinelenen kalem için variant.trial_period_days değerini ayarlayın. Kalem düzeyinde bir trial_period_days reddedilir.
  • Faturadaki her yinelenen kalemin aynı deneme süresine sahip olması gerekir.
  • Fatura hiçbir şey tahsil etmediğinde, denemeyi hemen başlatan bir payment_method_id ile veya collection_method: "send_invoice" ile düzenleyin ya da gönderin.
  • Panoda, özel bir yinelenen kalemin bir Free trial days alanı vardır. Bir ürünün faturalandırma planı kendi denemesini gösterir.

Belirli sayıda ödemeden sonra durdurun

Altı aylık ödeme gibi sabit bir ödeme planını faturalandırmak için yinelenen varyantta 2 ile 115 arasında bir split_pay_required_payments değeri ayarlayın. Fatura, varsa peşin ücret dahil ilk ödemedir. Örneğin 75 pes\cinu¨cretveu¨c\cadet40peşin ücret ve üç adet 40 taksit önce 115 ,ardından40, ardından 40 , ardından 40 $ faturalandırır. Whop bu sayıda ödeme yapıldığında yenilemeyi durdurur ve üyelik aktif kalır. Müşteri bundan önce aboneliği kendisi iptal edemez, ancak siz edebilirsiniz. Abonelik iptal edilene kadar yenilemek için bunu ayarlamadan bırakın.

Durumlar ve yaşam döngüsü

status değerlerini ödemelerden alır; bu nedenle bir fatura, bir ödeme devam ederken pending gibi bir ödeme durumu da gösterebilir. totals_status para alanlarının kesin olup olmadığını söyler: fatura taslakken estimated, düzenledikten sonra final. overdue, due_at tarihi geçmiş open veya uncollectible bir fatura için true olur.

Geçersiz kılın veya tahsil edilemez olarak işaretleyin

Void Invoice draft, open veya uncollectible durumundaki bir faturayı iptal eder. Zaten geçersiz kılınmış bir faturayı geçersiz kılmak onu değiştirmeden döndürür; ödenmiş bir fatura ise geçersiz kılınamaz. Tahsil etmeyi beklemediğinizi kaydetmek için bir faturayı tahsil edilemez olarak işaretleyin. Yalnızca open durumundaki bir fatura işaretlenebilir; tahsil edilemez bir faturayı yeniden işaretlemek onu değiştirmeden döndürür. Tahsil edilemez bir faturanın checkout_link değeri yoktur ve hatırlatma almaz. Bu örnek, open durumundaki bir faturayı tahsil edilemez olarak işaretler, ardından geçersiz kılar:

Bir faturayı silin

Delete Invoice, DELETE /invoices/{id} ile draft veya void durumundaki bir faturayı kaldırır. Yanıt { id, deleted: true } olur. Silinen bir fatura artık List Invoices veya List Payments içinde görünmez ve kimliği 404 döndürür. Bir silme işlemini geri alamazsınız. open durumundaki bir faturayı silmeden önce geçersiz kılın. Planlanmış bir gönderimi veya tahsilatı olan bir taslak önce Cancel Scheduled Send gerektirir. Taslak durumundaki bir yenileme faturası, bir aboneliği faturalandırdığı sürece silinemez. Para tahsil etmiş veya hâlâ bir banka havalesi bekleyen geçersiz kılınmış bir fatura silinemez; ödenmiş, beklemede veya tahsil edilemez bir fatura da silinemez. Bir faturanın deletable alanı, silinebildiğinde true olur. Silme işlemi invoice:update veya payment:charge gerektirir. Silinen bir taslağın numarası yeniden kullanılmaz.

Faturaları listeleyin ve getirin

List Invoices, kimlik bilginizin okuyabildiği faturaları en yeniden başlayarak döndürür. Bir API anahtarı kendi hesabını görür; bir kullanıcı token’ı ise kullanıcının ödemelerini okuyabildiği her hesabı görür. Listeyi şu sorgu parametreleriyle daraltın: Planlanmış bir taslak, scheduled_send_at değerine sahip olandır. open durumundaki bir fatura hiçbir zaman planlanmış değildir; vade tarihinde gönderilen bir taslak da öyle değildir. order (created_at, due_at veya scheduled_send_at) ve direction (asc veya desc) ile sıralayın. due_at veya scheduled_send_at ile sıralama, o tarihe sahip olmayan faturaları sona koyar. Yanıt { data, page_info } olur. page_info.has_next_page true olduğu sürece sonraki sayfayı okumak için page_info.end_cursor değerini after olarak iletin.
Retrieve Invoice bir faturayı pay_ kimliğiyle okur. List Payments taslakları dışarıda bırakır. Faturaları CSV dosyası olarak dışa aktarmak için Create Export çağrısını resource: "receipt_invoices" ile yapın. Bu, payment:basic:read ve payment:basic:export gerektirir. Müşteri sütunları yalnızca kimlik bilginizde ayrıca member:basic:read veya member:email:read bulunduğunda görünür.

Webhook’lar

Yerel faturalar, pay_ kimlikleri için ödeme webhook’ları gönderir. invoice.* olayları eski fatura API’sine aittir ve yerel faturalar bunları göndermez. payment.failed gibi diğer payment.* olayları da ödeme denemeleri değiştikçe faturanın pay_ kimliği için gelebilir. Bunlara webhook kılavuzu ile abone olun. Bir siparişi karşılamak için taslağı oluştururken faturanın id değerini siparişle birlikte kaydedin. Bir payment.succeeded olayının data alanı ödemedir, bu nedenle data.id faturanın pay_ kimliğidir. Olayı doğruladıktan sonra siparişi bu kimlikle arayın. Bu işleyicide orders kendi sipariş deponuzu temsil eder:
fulfilled kontrolü, yeniden teslim edilen bir olayın siparişi iki kez karşılamasını önler. Abonelik yenilemelerinin kendi pay_ kimlikleri vardır, bu nedenle bir faturayla eşleşmezler.

Fatura ödemelerinde ödeme kuralları

Ödeme kurallarınız, herhangi bir ödeme sayfasında olduğu gibi fatura ödemelerinde de Whop’un kendi dolandırıcılık taramasından sonra çalışır. Neler yapabilecekleri müşterinin mevcut olup olmadığına bağlıdır.
  • Düzenleme sırasındaki otomatik tahsilat oturum dışıdır. Bir block kuralı onu reddeder, bir allow kuralı ise onu diğer kurallarınızdan muaf tutar. Tahsilat oturum dışı olduğundan review ve enforce_3ds kuralları atlanır.
  • Ödeme bağlantısı üzerinden yapılan bir ödeme oturum içidir. Dolandırıcılığı yönetme bölümündeki uygunluk sınırlarıyla birlikte dört eylemin tümü uygulanır.
Otomatik tahsilatta kart koşulları kayıtlı ödeme yöntemini, faturalandırma koşulları ise faturanın faturalandırma adresini okur. customer_email, müşterinin Whop hesabındaki e-postadır. Ödemenin payment_rule_matches alanı kararı veren kuralı listeler. Atlanan bir kural listelenmez.

Panodaki faturalar

Invoices sayfası yerel faturaları listeler, oluşturur ve gönderir. Eski faturalar, Fatura gönderme sayfasının ele aldığı Legacy invoices sekmesindedir.

İzinler

Her yazma işlemi, Create Payment ile aynı izin olan payment:charge gerektirir; her okuma işlemi ise payment:basic:read gerektirir. invoice:* izinleri eski fatura API’sine aittir ve yerel faturalar bunları kullanmaz. Satır içi bir plan kalemi gönderen bir oluşturma veya güncelleme ayrıca plan:create gerektirir. Bazı alanlar kendi izinlerini gerektirir. Bu izin olmadan alan null olarak döner ve recipient_emails boş döner. Kimlik bilginiz bir POST isteğinden sonra bu okuma izinlerinden birini kaybederse, kayıtlı yanıt bu alanları gösterdiğinde isteği aynı Idempotency-Key ile yeniden oynatmak, error.code değeri invoice_replay_permission_revoked olan bir 403 ile reddedilir. Bunun yerine faturayı GET ile getirin. İzinleri İzinler kılavuzundan ekleyin.

Hatalar

Retler { error: { type, message, code } } olarak döner. Aksi belirtilmedikçe aşağıdaki her kod bir 400 olur. Bilinmeyen bir plan_id, member_id, mailing_address_id veya payment_method_id bir 404 olur; Whop’un okuyamadığı bir zaman damgası ise invalid_timestamp ile bir 400 olur. Bu retler error.code içermeyen bir 400 olur; bu nedenle nedeni öğrenmek için error.message değerini okuyun:
  • Bilinmeyen bir üst düzey alan.
  • 1 ile 999.999 aralığının dışında bir quantity.
  • recipient_emails içinde geçersiz bir adres veya 50’den fazla adres.
  • Faturalandırma dönemi uyuşmazlığı gibi ihlal edilmiş bir çoklu kalem kuralı.

Oluşturma ve güncelleme hataları

Düzenleme hataları

Gönderme ve planlama hataları

Bir taslağı göndermek onu düzenler; bu nedenle bir gönderim Düzenleme hataları bölümündeki herhangi bir nedenle de reddedilebilir.

Diğer hatalar

Ödenmiş bir faturayı geçersiz kılmak kodsuz bir 400 olur.

Sonraki adımlar

Faturalar API referansı

Tüm fatura uç noktaları, parametreleri ve yanıt alanları.

Ödeme yöntemlerini kaydedin

Bir faturanın düzenleme sırasında tahsilat yaptığı kayıtlı ödeme yöntemini toplayın.

Dolandırıcılığı yönetin

Fatura ödemelerini denetleyen ödeme kurallarını yazın.

Webhook'ları dinleyin

Faturalarınız için payment.created ve payment.succeeded olaylarını takip edin.