Faturalar

Abonelik motoru her faturalama döneminde bir fatura üretir — neyin borçlanıldığının ve tahsilat sırasında ne olduğunun kaydı. Bu sayfa faturaları okumayı, iki mutasyonu (void, retry-charge) ve başarısız çekimleri pes etmeden önce tekrar deneyen dunning mekanizmasını anlatır.

Tüm endpoint'ler secret key'inizi Bearer token olarak kullanır ve https://api-gateway.lunixi.com/api/v1/subscriptions altındadır. Liste endpoint'leri cursor pagination kullanır (pageSize, pageToken).

⚠️

Tüm fatura tutarları minor-unit (kuruş) integer'dır — "amount": 149900 = ₺1.499,00.

Fatura yaşam döngüsü

Dunning bir hata durumu değil, zamanlanmış bir tahsilat programıdır: haklar tükenene kadar fatura açık kalır. Deneme başarılı olursa invoice.paid gecikmeli olarak gelir — webhook tüketiciniz bunu geç gelen bir başarı olarak karşılamalı.

POST :id/void, açık bir faturayı akıştan her an çıkarabilir (invoice.voided).

Status değerleri

Faturanın status alanı tam olarak şu değerleri alır:

`status`	Anlamı
`DRAFT`	Henüz finalize edilmedi — çekim tetiklenmez
`OPEN`	Finalize edildi — tahsilat denenir
`PAID`	Tamamen tahsil edildi — terminal
`UNCOLLECTIBLE`	Max dunning denemesi tükendi — terminal
`VOID`	Manuel iptal edildi — terminal

Geçişler DRAFT → OPEN → PAID | UNCOLLECTIBLE | VOID şeklindedir; üç terminal status bir daha değişmez.

Listeleme & detay

Method	Path	Ne yapar
`GET`	`/subscriptions/invoices`	Faturaları listeler (cursor pagination)
`GET`	`/subscriptions/invoices/:id`	Tek fatura — kalemleri ve tahsilat geçmişiyle

curl "https://api-gateway.lunixi.com/api/v1/subscriptions/invoices?pageSize=20" \
  -H "Authorization: Bearer at_live_5f3e2b1a..."

{
  "id": "inv_01JX9A2C6R",
  "subscriptionId": "sub_01JX5B8R3M",
  "status": "OPEN",
  "amount": 149900,
  "currency": "TRY",
  "periodStart": "2026-07-01T00:00:00Z",
  "periodEnd": "2026-08-01T00:00:00Z"
}

Fatura void etme

POST /subscriptions/invoices/:id/void, açık bir faturayı iptal eder — o fatura için başka tahsilat denemesi yapılmaz. İyi niyet indirimi, faturalama hatası veya bir anlaşmazlığı sistem dışında çözdüğünüz durumlar için kullanın. invoice.voided üretir.

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/invoices/inv_01JX9A2C6R/void \
  -H "Authorization: Bearer at_live_5f3e2b1a..."

Çekimi tekrar deneme

POST /subscriptions/invoices/:id/retry-charge, otomatik dunning takviminin dışında, anında bir tahsilat denemesi tetikler. Tipik kullanım: müşteri kartını yeni güncelledi (subscription.payment_card_swapped veya card.added aldınız) ve bir sonraki zamanlanmış denemeyi beklemek yerine hemen tahsil etmek istiyorsunuz.

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/invoices/inv_01JX9A2C6R/retry-charge \
  -H "Authorization: Bearer at_live_5f3e2b1a..."

Dunning modeli

AUTO_CHARGE tahsilatı başarısız olduğunda fatura dunning'e girer: şeklini plan üzerinde tanımladığınız otomatik tekrar deneme takvimi — bkz. Planlar:

Plan alanı	Dunning'deki rolü
`maxDunningAttempts`	Pes etmeden önce kaç otomatik deneme yapılacağı
`dunningScheduleDays`	Her denemenin ne zaman koşacağı; ilk başarısızlıktan itibaren gün ofsetleri (örn. `[1, 3, 7]`)
`gracePeriodDays`	Fatura ödenmemişken aboneliğin entitlement'larını ne kadar süre koruyacağı

Akış, event event:

`invoice.payment_failed`

İlk çekim (veya bir deneme) başarısız oldu. Burada aksiyon alın: müşteriye e-posta gönderin, uygulama içi banner gösterin, kartını güncellemesi için müşteri portalına yönlendirin.

Zamanlanmış denemeler

Platform, dunningScheduleDays'e göre tekrar dener. Başarısız her deneme yeni bir invoice.payment_failed üretir; başarılı olan invoice.paid üretir ve dunning biter. Manuel retry-charge da aynı faturanın tahsilat denemesi sayılır.

`invoice.uncollectible`

maxDunningAttempts hakkının tamamı tükendi. Fatura tahsil edilemez olarak işaretlenir — politikanıza siz karar verin: erişimi askıya alın, aboneliği kısıtlı modda tutun ya da tutarı silin.

gracePeriodDays boyunca müşteri, fatura ödenmemiş olsa da erişimini korur — dunning bir kurtarma penceresidir, anlık kesinti değil. Plan değerlerini ürününüzün ne kadar toleranslı olmasını istediğinize göre seçin.

Payment method lost

AUTO_CHARGE aboneliğinin arkasındaki kayıtlı kart kullanılamaz hâle gelirse — silinmiş, ya da yenisi olmadan süresi dolmuş — platform subscription.payment_method_lost event'ini üretir ve aboneliğin tahsilatını MANUAL'e çevirir: faturalar kesilmeye devam eder ama hiçbiri otomatik çekilmez.

Kurtarma: müşteri yeni kart ekler (portal cards/update veya merchant API POST /subscriptions/cards + set-default), sonra açık faturaları retry-charge ile tahsil edersiniz ve isterseniz aboneliği tekrar AUTO_CHARGE'a alırsınız.

Hatalar

Durum	Anlamı	Ne yapmalı
`401`	Eksik/geçersiz Bearer key	`Authorization` header'ını kontrol edin
`404`	Fatura bulunamadı	Id'nin hesabınıza ait olduğunu doğrulayın
`409`	Geçersiz durum (ödenmiş faturayı void etmek, void/ödenmiş faturaya retry-charge)	`GET /invoices/:id` ile güncel durumu okuyup ona göre davranın
`422`	Tekrar deneme mümkün değil — örn. abonelikte kullanılabilir kart yok	Önce müşterinin kart eklemesini sağlayın, sonra tekrar deneyin

Webhooks

Event	Ne zaman
`invoice.created`	Dönem faturası oluşturuldu
`invoice.paid`	Tahsilat başarılı (otomatik, retry-charge veya manuel kapatma)
`invoice.payment_failed`	Bir çekim denemesi başarısız — dunning işliyor
`invoice.uncollectible`	Dunning tükendi; fatura otomatik tahsil edilmeyecek
`invoice.voided`	Fatura void edildi
`subscription.payment_method_lost`	Kayıtlı kart kullanılamaz — tahsilat `MANUAL`'e düştü

Teslimat ve imza doğrulaması için Webhooks sayfasına bakın.

Sonraki adımlar

Planlar — maxDunningAttempts, dunningScheduleDays, gracePeriodDays yapılandırması
Abonelikler — tahsilat yöntemleri ve yaşam döngüsü
Müşteri Portalı — müşterilerin başarısız ödemelerini kendilerinin düzelttiği yer

Müşteri Portalı Kullanım & Entitlement