Skip to main content
Yerel faturalar eski faturalarla aynı /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çin 4.99 kullanın. 499 göndermek 499 USD faturalandırır.
Yerel istek bir taslak oluşturur. Düzenlemek ve e-postayla göndermek için 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-1 sü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_address ve customer_name yalnızca oluşturma sırasında kullanılan girdilerdir.
  • Düzenlenmiş tutarlar ve kalemler kilitlidir. Yalnızca memo ve/veya recipient_emails içeren bir güncellemeye, planlanmış bir taslak dahil draft, open ve uncollectible faturalarda 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:
  1. Nihai vergiyi hesaplamak ve ilk fatura e-postasını göndermeden ödemeye açmak için POST /invoices/{id}/issue ile düzenleyin.
  2. Veya POST /invoices/{id}/send ile gönderin. Bu, taslağı düzenler. Kayıtlı bir yöntemi hemen ücretlendirmediği sürece alıcılara e-posta gönderir. open bir faturayı göndermek onu yeniden e-postayla gönderir. send_at bir taslağın gönderimini planlar. POST /invoices/{id}/unschedule bu planı iptal eder.
  3. Taslakta payment_method_id ayarlayarak kayıtlı bir yöntemi ücretlendirin. Pozitif bir toplam için düzenleme veya gönderme, gelecekteki bir charge_at zamanında, yoksa gelecekteki bir due_at zamanında, o da yoksa hemen ücretlendirir. charge_at gelecekte olmalıdır ve send_at öncesinde olamaz.
Hemen ücretlendiren bir taslağı göndermek ilk fatura e-postasını atlar. Daha sonra ücretlendirecek şekilde göndermek e-postayı şimdi gönderir. Başarısız bir otomatik ücretlendirme, Issue Invoice kullanmış olsanız bile bir ödeme bağlantısı e-postasını tetikleyebilir. Kayıtlı bir ödeme yöntemini ücretlendirin akışı açıklar. 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 faturalar pay_ 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

  1. Eski API’de kalması gereken iş akışları için Geçişten önce bölümünü kontrol edin.
  2. 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.
  3. Miktarları, fiyatları, para birimini ve ürün gereksinimlerini kontrol ederek uygun varyantlardan items oluşturun.
  4. 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.
  5. 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.
  6. Yerel pay_ ve eski inv_ kimliklerini ayrı tutun. Eski okumaları önceki sürümde tutun.
  7. Tutarları para nesnelerinden okuyun ve ödeme sayfasını imzalı checkout_link ile açın.
  8. overdue ve ek ödeme durumlarını ele alın.
  9. Siparişi faturanın ödeme kimliği için payment.succeeded üzerinden tamamlayın.
  10. 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ığı.