/invoices yollarını kullanır, ancak farklı bir istek biçimine ve yaşam döngüsüne sahiptir. Bu kılavuz, bir entegrasyonu taşırken değiştirmeniz gereken alanları ve işlemleri eşler.
Ortak yollar
Api-Version-Date: 2026-10-24 sürümünden itibaren yerel faturalara yönlendirilir.
Aşağıdaki yerel örnekler, güncel varyant alan adları ve müşteri kilitleme kurallarıyla
Api-Version-Date: 2026-11-02-1 kullanır. Bu başlığı her yerel istekte gönderin.
Eski çağrıları 2026-10-15-1 gibi daha önce yayınlanmış bir sürümde tutun.
API sürümleri başlıkların kimlik bilgisi sabitlemelerini
nasıl geçersiz kıldığını açıklar.Neler değişiyor
Yerel API eski
inv_ faturalarını listelemez veya getirmez. Mevcut eski faturaları önceki API sürümüyle okumaya devam edin. Yerel bir fatura oluşturmak ayrı bir fatura oluşturur. Eski bir faturayı dönüştürmez veya kapatmaz.
Geçişten önce
Bir akışı taşımadan önce bu farklılıkları kontrol edin. Akış, yerel API’nin sağlamadığı bir özelliğe ihtiyaç duyuyorsa onu eski API’de tutun.Oluşturma isteğini eşleyin
Eski bir oluşturma isteği tek bir plan ve isteğe bağlı olarak fiyatını bölen etiketler gönderir. Yerel bir oluşturma isteği, faturalandırılan her varyant için bir kalem gönderir. Bu örnekler toplam 19.99 USD kalem fiyatı belirler. Mevcut yerel varyant 15 USD’lik kurulum ücretini temsil eder. 4.99 USD’lik hizmet bedeli, ürünü olmayan özel bir tek seferlik ücrettir. Her iki API de fiyatları para birimi cinsinden kabul eder. 4.99 USD için4.99 kullanın. 499 göndermek 499 USD faturalandırır.
POST /invoices/{id}/send ile gönderin. member_id bir aboneliği (mem_) değil, bir müşteriyi (mber_) tanımlar.
2026-10-27-2 öncesindeki yerel sürümler için variant_id, variant ve billing_type yerine plan_id, plan ve plan_type kullanın. Bu eski sürümlerde yanıtın satır kalemleri de plan_id kullanır.
Düzenlenmiş tutarları kilitli tutun
PATCH /invoices/{id} bir taslağın kalemlerini ve faturalandırma ayrıntılarını düzenler. items göndermek, varyantların güncel fiyatlarını kullanarak listenin tamamını değiştirir. Atlanması, kaydedilmiş kalemleri ve fiyatları korur.
- Kalemleri veya faturalandırma ayrıntılarını düzenlemeden önce planlanmış bir gönderimi iptal edin.
2026-11-02-1sürümünden itibaren bir taslağa atanmış müşteriyi değiştiremez veya temizleyemezsiniz. Müşterisi olmayan bir taslağa yine de müşteri atanabilir. Başka biri için yeni bir fatura oluşturmadan önce taslağı geçersiz kılın.email_addressvecustomer_nameyalnızca oluşturma sırasında kullanılan girdilerdir.- Düzenlenmiş tutarlar ve kalemler kilitlidir. Yalnızca
memove/veyarecipient_emailsiçeren bir güncellemeye, planlanmış bir taslak dahildraft,openveuncollectiblefaturalarda izin verilir.
Düzenleme, gönderme ve ücretlendirme
Eski bir oluşturma isteği tahsilat davranışınıcollection_method ile seçer. Yerel faturalar, taslağı oluşturduktan sonra ayrı çağrılar kullanır:
- Nihai vergiyi hesaplamak ve ilk fatura e-postasını göndermeden ödemeye açmak için
POST /invoices/{id}/issueile düzenleyin. - Veya
POST /invoices/{id}/sendile gönderin. Bu, taslağı düzenler. Kayıtlı bir yöntemi hemen ücretlendirmediği sürece alıcılara e-posta gönderir.openbir faturayı göndermek onu yeniden e-postayla gönderir.send_atbir taslağın gönderimini planlar.POST /invoices/{id}/unschedulebu planı iptal eder. - Taslakta
payment_method_idayarlayarak kayıtlı bir yöntemi ücretlendirin. Pozitif bir toplam için düzenleme veya gönderme, gelecekteki bircharge_atzamanında, yoksa gelecekteki birdue_atzamanında, o da yoksa hemen ücretlendirir.charge_atgelecekte olmalıdır vesend_atöncesinde olamaz.
open yanıtı ödemeyi onaylamaz. Siparişi tamamlamadan önce payment.succeeded olayını bekleyin. Açık bir faturayı ücretlendirmek veya yeniden denemek için Charge Invoice kullanın. Faturayı yeniden düzenlemek veya göndermek başka bir ücretlendirme başlatmaz.
Yinelenen bir varyant için Issue Invoice veya Send Invoice üzerindeki collection_method yenilemeleri kontrol eder. charge_automatically gelecekteki ödemeleri otomatik olarak tahsil eder. send_invoice her dönem yeni bir fatura oluşturur ve e-postayla gönderir. İlk faturanın tahsilatı için payment_method_id yerine geçmez. Bkz. Bir aboneliği faturalandırın.
Yanıtı eşleyin
Bir PDF indirmek için kısa ömürlü bir bağlantı almak üzere
POST /invoices/{id}/generate_pdf çağırın.
Fatura ödeme sayfasını açın
checkout_link, bir . ile ayrılmış fatura kimliğini ve imzalı bir token’ı içerir. Bu fatura için bir oturum açmak üzere değerin tamamını link olarak POST /checkout_sessions uç noktasına iletin. Müşteriye yönelik bir URL için Barındırılan ödeme sayfası URL’sini oluşturun adımlarını izleyin.
Alan yalnızca ödeme sayfası kullanılabilir olduğunda bulunur: fatura open olmalıdır. Kurumsal alıcılar ve iptal edilmiş üyelikler bu ödeme sayfasını kullanamaz. Anahtarınızın payment:charge iznine veya faturada kayıtlı bir ödeme yöntemi yoksa invoice:create/invoice:update iznine ihtiyacı vardır. Taslak, ödenmiş, geçersiz kılınmış veya tahsil edilemez bir faturada ve kurumsal alıcılar için null olur.
Durumları eşleyin
Yerel faturalar ayrıca
authorized, pending veya unresolved döndürebilir. Eski enum dışındaki her durumu ödenmiş veya başarısız olarak değerlendirmeyin. Durumlar ve yaşam döngüsü bunları açıklar.
Uç noktaları eşleyin
Webhook’ları eşleyin
Yerel faturalarpay_ kimlikleri için ödeme olayları gönderir. invoice.* olayları eski faturaları tanımlar.
Ödeme olayları faturalarla ilgisi olmayan ödemeleri de kapsar. Olayın ödeme kimliğini sakladığınız yerel fatura kimlikleriyle eşleştirin. Webhook’lar,
payment.succeeded üzerinden siparişin nasıl tamamlanacağını gösterir.
İzinler
member:basic:read müşteri adlarını ve üye/üyelik kimliklerini gösterir. member:email:read, email_address ve recipient_emails alanlarını gösterir. Ödeme yöntemi ve adres alanları payment:basic:read gerektirir.
Geçiş kontrol listesi
- Eski API’de kalması gereken iş akışları için Geçişten önce bölümünü kontrol edin.
- Yerel çağrıları alan adlarıyla eşleşen yayınlanmış bir sürüme sabitleyin; örneğin bu örnekler için
2026-11-02-1. - Miktarları, fiyatları, para birimini ve ürün gereksinimlerini kontrol ederek uygun varyantlardan
itemsoluşturun. - Eski tek çağrılık oluşturmayı, oluşturma ve ardından düzenleme veya gönderme ile değiştirin. İlk fatura için kayıtlı yöntemle ücretlendirmeyi, yenilemeler için bir tahsilat yöntemini seçin.
- Son ödeme tarihlerini, planlanmış gönderimleri ve alıcı ücretlerini yalnızca alan adlarına göre değil, davranışlarına göre eşleyin.
- Yerel
pay_ve eskiinv_kimliklerini ayrı tutun. Eski okumaları önceki sürümde tutun. - Tutarları para nesnelerinden okuyun ve ödeme sayfasını imzalı
checkout_linkile açın. overdueve ek ödeme durumlarını ele alın.- Siparişi faturanın ödeme kimliği için
payment.succeededüzerinden tamamlayın. - Satır içi varyant/ürün ve müşteri okuma izinleri dahil olmak üzere akışınızın kullandığı izinleri verin.
Sonraki adımlar
Faturalar kılavuzu
Yerel faturaları oluşturun, düzenleyin, gönderin ve tahsil edin.
Faturalar API referansı
Her yerel fatura uç noktası ve alanı.
Eski fatura API'si
Mevcut entegrasyonunuzun çağırdığı uç noktalar.
API sürümleri
Api-Version-Date ve sürüm sabitlemelerinin nasıl çalıştığı.
