Abonelikler

Bir abonelik, bir müşteriyi bir plana bağlar ve faturalama motorunu çalıştırır: deneme süreleri, dönem faturaları, dunning, plan değişiklikleri ve iptal. Bu sayfa merchant API üzerinden yaşam döngüsünün tamamını anlatır.

Tüm endpoint'ler secret key'inizi Bearer token olarak kullanır ve https://api-gateway.lunixi.com/api/v1/subscriptions/subscriptions altındadır — segment bilerek iki kez geçer: ilk subscriptions ürün alanı, ikincisi bu kaynak grubudur. Liste endpoint'leri cursor pagination kullanır (pageSize, pageToken).

Yaşam döngüsü tek bakışta

Her geçiş bir webhook üretir — subscription.created, subscription.activated, subscription.paused, subscription.resumed, subscription.canceled — böylece sisteminiz polling yapmadan durumu yansıtabilir. Event tablosunun tamamı sayfanın sonunda.

Status değerleri

Aboneliğin status alanı tam olarak şu değerleri alır (liste endpoint'ini status ile filtreleyebilirsiniz):

Entitlement'lar status ACTIVE veya PAST_DUE iken geçerlidir. Terminal status'lar (UPGRADED, DOWNGRADED, CANCELED, EXPIRED) bir daha başka duruma geçmez.

Abonelik oluşturma

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/subscriptions \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_01JX2F9K4T",
    "planId": "plan_01JX2G3M8V",
    "idempotencyKey": "order-84172-sub",
    "paymentCardId": "card_01JX2H5N1Q",
    "collectionMethod": "AUTO_CHARGE",
    "skipTrial": false,
    "startsAt": "2026-08-01T00:00:00Z"
  }'

{
  "success": true,
  "data": {
    "id": "sub_01JX5B8R3M",
    "customerId": "cust_01JX2F9K4T",
    "planId": "plan_01JX2G3M8V",
    "status": "TRIALING",
    "collectionMethod": "AUTO_CHARGE",
    "currentPeriodEnd": "2026-09-01T00:00:00Z"
  }
}

Tahsilat yöntemleri

Deneme süreleri

Planın trialPeriodDays > 0 ise abonelik denemede başlar: entitlement'lar aktiftir, ancak deneme bitene kadar çekim yapılmaz. Denemeyi atlayıp hemen faturalamak için create'te skipTrial: true gönderin.

Deneme bitmeden önce platform subscription.trial_will_end event'ini üretir — müşteriye ödeme yöntemi eklemesini/onaylamasını hatırlatmak için kullanın. Deneme bitince ilk dönem faturası oluşturulur ve collectionMethod'a göre tahsil edilir; abonelik subscription.activated üretir.

İptal

POST /api/v1/subscriptions/subscriptions/:id/cancel

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/subscriptions/sub_01JX5B8R3M/cancel \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{ "cancelAtPeriodEnd": true }'

subscription.canceled event'ini üretir. Müşteriler müşteri portalı üzerinden kendi kendilerine de iptal edebilir — o yol, fraud koruması olarak ayrıca e-posta onay token'ı ister.

Duraklat & devam ettir

POST /api/v1/subscriptions/subscriptions/:id/pause faturalamayı askıya alır; otomatik yeniden başlatma zamanlamak için opsiyonel resumeAt gönderin. POST /api/v1/subscriptions/subscriptions/:id/resume hemen yeniden aktifleştirir.

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/subscriptions/sub_01JX5B8R3M/pause \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{ "resumeAt": "2026-10-01T00:00:00Z" }'
 
# daha sonra, ya da resumeAt yerine:
curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/subscriptions/sub_01JX5B8R3M/resume \
  -H "Authorization: Bearer at_live_5f3e2b1a..."

Duraklatılmışken dönem faturası oluşturulmaz. subscription.paused ve subscription.resumed event'lerini üretir.

Plan değiştirme (yükseltme / düşürme)

POST /api/v1/subscriptions/subscriptions/:id/change-plan — hedef newPlanId ve bir behavior ile:

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/subscriptions/sub_01JX5B8R3M/change-plan \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "newPlanId": "plan_01JX2G9P7W",
    "behavior": "NEXT_PERIOD"
  }'

Yaygın desen: yükseltmeler IMMEDIATE (müşteri büyük planı hemen alır), düşürmeler NEXT_PERIOD (ödediği dönemi sonuna kadar kullanır).

Sorgulama, listeleme & audit

Audit log, "bu müşterinin planı neden değişti?" gibi destek soruları için başvuracağınız araçtır — yukarıdaki her mutasyon zaman damgası ve kaynağıyla orada görünür.

Hatalar

Webhooks

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

Sonraki adımlar

• Faturalar — dönem faturaları, dunning ve retry-charge
• Müşteri Portalı — müşterilerin aboneliklerini kendilerinin yönetmesi
• Özellikler & Eklentiler — abonelik başına eklenti ücretleri
• Kullanım & Entitlement — metered faturalama ve kota kontrolleri