Planlar

Plan, bir ürünü müşterinin abone olabileceği bir şeye dönüştürür: bir fiyat, bir para birimi, opsiyonel bir deneme süresi ve motora her faturanın ne zaman üretileceğini söyleyen bir billing kuralı. Başarısızlık senaryosu da planın sorumluluğundadır — başarısız çekimin kaç kez yeniden deneneceği (maxDunningAttempts), hangi günlerde deneneceği (dunningScheduleDays) ve tahsilat kovalanırken müşterinin erişimi ne kadar koruyacağı (gracePeriodDays).

Endpoint'ler

Hepsi Bearer ile doğrulanır (at_live_…); listeler cursor pagination kullanır (pageSize, pageToken; productId / includeArchived ile filtre).

Plan oluşturma

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/plans \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "prd_4b2e88",
    "code": "pro-monthly",
    "name": "Pro Aylık",
    "price": 49900,
    "currency": "TRY",
    "trialPeriodDays": 7,
    "billing": {
      "frequency": "MONTHLY",
      "interval": 1,
      "byMonthDay": [15],
      "timezone": "Europe/Istanbul",
      "lastDayOfMonthFix": true
    },
    "maxDunningAttempts": 3,
    "dunningScheduleDays": [1, 3, 7],
    "gracePeriodDays": 7
  }'

Alanlar

Billing kuralı

billing nesnesi bir tekrarlama kuralıdır — RRULE ile aynı yapı taşları:

Hazır tarifler:

{ "frequency": "MONTHLY", "interval": 1,  "timezone": "Europe/Istanbul", "lastDayOfMonthFix": true }          // klasik aylık
{ "frequency": "MONTHLY", "interval": 3,  "byMonthDay": [1], "timezone": "Europe/Istanbul", "lastDayOfMonthFix": true }  // üç ayda bir, ayın 1'inde
{ "frequency": "WEEKLY",  "interval": 1,  "byWeekDay": ["MO"], "timezone": "Europe/Istanbul", "lastDayOfMonthFix": false } // her pazartesi
{ "frequency": "YEARLY",  "interval": 1,  "timezone": "Europe/Istanbul", "lastDayOfMonthFix": true, "count": 3 }          // 3 yıllık çekim, sonra biter

Güncelleme & arşivleme

PATCH /api/v1/subscriptions/plans/:id; name, description, price, trialPeriodDays, billing, dunning alanları ve metadata'yı (artı audit için reason) günceller. Bir fiyat güncellemesinin mevcut abonelere ulaşıp ulaşmayacağı ve ne zaman ulaşacağı ürün/abonelik fiyat politikasınca belirlenir (LOCKED / FOLLOW_PLAN, IMMEDIATE / NEXT_PERIOD) — bkz. Ürünler.

DELETE /api/v1/subscriptions/plans/:id planı arşivler: artık abone olunamaz ve public katalogdan çıkar; ancak üzerindeki mevcut abonelikler normal faturalanmaya devam eder.

curl -X DELETE https://api-gateway.lunixi.com/api/v1/subscriptions/plans/pln_9f3a1c \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "pro-monthly-v2 ile değiştirildi" }'

Çeviriler & vitrin metinleri

Plan name / description alanları tıpkı ürünlerdeki gibi yerelleşir — PATCH …/plans/:id/translations/:locale ve { "name": …, "description": … }; locale geçilen her yerde (public catalog, portal) otomatik sunulur.

Pricing sayfanızda planın altındaki pazarlama maddeleri — "500 işlem / ay", "Öncelikli destek" — planın vitrin özellikleridir: sıralı, locale bazlı görüntüleme metinleri; merchant panelinden yönetilir ve Public Catalog API'de planla birlikte döner. Bunlar yalnızca sunumdur; zorlanabilir kotalar Özellikler & entitlement tarafında yaşar.

Yanıt

{
  "id": "pln_9f3a1c",
  "productId": "prd_4b2e88",
  "code": "pro-monthly",
  "name": "Pro Aylık",
  "price": 49900,
  "currency": "TRY",
  "trialPeriodDays": 7,
  "billing": {
    "frequency": "MONTHLY",
    "interval": 1,
    "byMonthDay": [15],
    "timezone": "Europe/Istanbul",
    "lastDayOfMonthFix": true
  },
  "maxDunningAttempts": 3,
  "dunningScheduleDays": [1, 3, 7],
  "gracePeriodDays": 7,
  "isActive": true,
  "createdAt": "2026-07-06T09:31:00Z"
}

Plan değişikliği

Mevcut bir aboneyi başka plana taşımak planın değil aboneliğin işlemidir: POST /api/v1/subscriptions/subscriptions/:id/change-plan, behavior: "IMMEDIATE" (hemen geçir ve mahsuplaş) veya "NEXT_PERIOD" (dönem sınırına planla) ile. Upgrade, downgrade ve ürettikleri event'ler Abonelikler sayfasında anlatılır.

Hatalar

Webhook'lar

Sonraki adımlar

• Abonelikler — müşteri abone etme, iptal, duraklatma, plan değişikliği
• Ürünler — fiyat-değişikliği politikası ve katalog çevirileri
• Pricing & Portal SDK — bu planları kendi pricing sayfanızda gösterin
• Faturalar — billing kuralının her dönem ürettiği şey