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ğipay_ 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.
- 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.
- 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.
- 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.
- Siparişi
payment.succeededwebhook’undan karşılarsınız.
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.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.
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
quantitykullanı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.
quantity1 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_paymentsdeğ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.
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.
itemstü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_iddeğiştirmek, yenilerini göndermediğiniz sürece kayıtlı faturalandırma adresini ve ödeme yöntemini kaldırır.recipient_emailskorunur; bu yüzden yeni bir liste de gönderin, aksi halde önceki müşteri fatura e-postasını almaya devam eder.email_addressvecustomer_namekabul edilmez. Başka birini faturalandırmak için farklı birmember_idgönderin.- Planlanmış gönderimi olan bir taslak, gönderimi iptal edene kadar yalnızca
recipient_emailsdeğişikliğini kabul eder. - Fatura düzenlendikten sonra yapabileceğiniz tek değişiklik, tek başına gönderilen
recipient_emailsdeğişikliğidir ve bu yalnızca faturaopenveyauncollectibledurumundayken mümkündür. Diğer tüm düzenlemeler400ile 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:
- Create Payment işleminin kayıtlı bir ödeme yönteminde çalıştırdığı kontrollerin aynısını çalıştırır.
- Faturalandırılan miktarlar için stok ayırır ve ödemenin ücretlerini hazırlar.
- Faturayı
openolarak döndürür ve yöntemden oturum dışı tahsilat yapar. Tahsilat, Issue Invoice veya Send Invoice çağrısına ilettiğinizcharge_atzamanında; aksi halde hâlâ ilerideysedue_atzamanında; aksi halde hemen gerçekleşir.scheduled_charge_athenüz gerçekleşmemiş bir tahsilatı gösterir.
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.
Faturayı düzenleyin
Issue Invoice bir taslağı açık bir faturaya dönüştürür. Whop faturayı yeniden kontrol eder, nihai vergiyi hesaplar vestatus 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_amountbir taslaktanullolur ve faturayı düzenlediğinizde ayarlanır.totalveamount_duebunu 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.createdolayı, faturanınpay_kimliği için bir kez tetiklenir.- Yeniden düzenlemek güvenlidir. Zaten
openolan 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.
Ödeme bağlantısını alın
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.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.
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_emailsiçindeki her giriş.
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.
opendurumundaki bir faturadarecipient_emailsdeğ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çinsend_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_atgelecekte 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_atile yeniden gönderin. - Gönderim gerçekleşene veya siz iptal edene kadar düzenleme kilitlidir. Yalnızca
recipient_emailsdeğ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}/unscheduleile Cancel Scheduled Send.scheduled_send_atyenidennullolur 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.
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.
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.- 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-11API sürümünden itibaren ilk faturasıinitial_priceilerenewal_pricetoplamı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 kaleminininitial_pricedeğeriunit_amountiçindeki bu tek seferlik kısmı belirtir; fatura sayfası, e-posta ve PDF bunu kendi Upfront fee satırında listeler. - 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. - 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.
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ıntrial_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_priceilerenewal_pricetoplamını faturalandırır. Yenileme faturaları hiçbir zaman deneme başlatmaz. - Deneme varyanttan gelir. Özel bir yinelenen kalem için
variant.trial_period_daysdeğerini ayarlayın. Kalem düzeyinde birtrial_period_daysreddedilir. - 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_idile veyacollection_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 birsplit_pay_required_payments değeri ayarlayın. Fatura, varsa peşin ücret dahil ilk ödemedir. Örneğin 75 taksit önce 115 , 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 Invoicedraft, 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.
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
blockkuralı onu reddeder, birallowkuralı ise onu diğer kurallarınızdan muaf tutar. Tahsilat oturum dışı olduğundanreviewveenforce_3dskuralları 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.
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_emailsiç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.
