Ürünler

Ürün, kataloğunuzun kökündeki satılabilir birimdir — "Pro", "Enterprise", "Depolama Paketi". Kendi fiyatı yoktur; fiyatları ve faturalama ritimlerini ona planlar bağlar. Ürünün sahip olduğu şeyler: sizin sabit code'unuz, müşteriye görünen ad ve açıklama, locale bazlı çeviriler ve planlarındaki aboneliklere miras kalan varsayılan fiyat-değişikliği politikası.

Endpoint'ler

Tüm endpoint'ler Bearer ile doğrulanır (at_live_…); liste yanıtları cursor pagination kullanır (pageSize, pageToken).

Method	Path	Ne yapar
POST	`/api/v1/subscriptions/products`	Ürün oluşturur
GET	`/api/v1/subscriptions/products`	Listeler (`includeArchived` filtresi, `pageSize` / `pageToken` sayfalama)
GET	`/api/v1/subscriptions/products/:id`	Tek ürünü getirir
PATCH	`/api/v1/subscriptions/products/:id`	Alanları günceller
DELETE	`/api/v1/subscriptions/products/:id`	Arşivler (soft delete)
GET	`/api/v1/subscriptions/products/:id/translations`	Çevirileri listeler
PATCH	`/api/v1/subscriptions/products/:id/translations/:locale`	Çeviri oluşturur veya günceller

Ürün oluşturma

curl -X POST https://api-gateway.lunixi.com/api/v1/subscriptions/products \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "pro",
    "name": "Pro",
    "description": "Büyüyen ekipler için",
    "defaultPriceUpdatePolicy": "LOCKED",
    "defaultPriceChangeBehavior": "NEXT_PERIOD",
    "metadata": { "tier": 2 }
  }'

Alanlar

Alan	Tip	Not
`code`	string, zorunlu	Sizin sabit kimliğiniz; entegrasyonlarda kullanılır, merchant başına benzersizdir.
`name`	string, zorunlu	Müşteriye görünen ad (temel locale).
`description`	string	Müşteriye görünen açıklama.
`defaultPriceUpdatePolicy`	`LOCKED` \| `FOLLOW_PLAN`	Bu ürünün planlarında açılan abonelikler için varsayılan: `LOCKED` müşterinin kaydolduğu fiyatı sabitler; `FOLLOW_PLAN` sonraki plan fiyat değişikliklerini takip eder. Abonelik başına ezilebilir (`priceUpdatePolicy`).
`defaultPriceChangeBehavior`	`IMMEDIATE` \| `NEXT_PERIOD`	Takip edilen fiyat değişikliğinin ne zaman devreye gireceği: hemen ya da bir sonraki faturalama döneminde.
`metadata`	object	Okumalarda aynen geri dönen serbest key/value deposu.

Bu iki politika alanını grandfathering şalteriniz olarak düşünün. LOCKED + NEXT_PERIOD en muhafazakâr duruştur: mevcut aboneler fiyatını korur; uygulanacak bir değişiklik varsa da dönem sınırını bekler.

Güncelleme

PATCH /api/v1/subscriptions/products/:id; name, description, defaultPriceUpdatePolicy, defaultPriceChangeBehavior, isActive, metadata alanlarının herhangi bir alt kümesini ve audit izine yazılan opsiyonel bir reason alanını kabul eder.

curl -X PATCH https://api-gateway.lunixi.com/api/v1/subscriptions/products/prd_4b2e88 \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Pro Plus", "reason": "Q3 rebrand" }'

Arşivleme — DELETE soft'tur

DELETE hiçbir zaman veri silmez. Ürünü arşivler: public katalogdan ve varsayılan listelerden kaybolur; mevcut planlar ve abonelikler çalışmaya devam eder, geçmiş bozulmaz.

curl -X DELETE https://api-gateway.lunixi.com/api/v1/subscriptions/products/prd_4b2e88 \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "satıştan kaldırıldı" }'

Arşivlenen ürünlere erişim sürer: GET /api/v1/subscriptions/products?includeArchived=true.

Çeviriler — çok dilli katalog

Her ürün, name ve description için locale bazlı override taşır. Çağıran taraf locale gönderdiğinde Public Catalog API ve portal bunları otomatik sunar — tek katalog, pricing sayfanızın konuştuğu her dil.

curl -X PATCH https://api-gateway.lunixi.com/api/v1/subscriptions/products/prd_4b2e88/translations/en \
  -H "Authorization: Bearer at_live_5f3e2b1a..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pro",
    "description": "For growing teams"
  }'

:locale segmenti BCP-47 tarzı etiketleri kabul eder (tr, en, en-US, de-DE). PATCH bir upsert'tür — aynı çağrı eksik locale'i oluşturur, mevcut olanı günceller; GET …/translations tanımlı her şeyi listeler.

Yanıt

{
  "id": "prd_4b2e88",
  "code": "pro",
  "name": "Pro",
  "description": "Büyüyen ekipler için",
  "defaultPriceUpdatePolicy": "LOCKED",
  "defaultPriceChangeBehavior": "NEXT_PERIOD",
  "isActive": true,
  "metadata": { "tier": 2 },
  "createdAt": "2026-07-06T09:30:00Z"
}

Liste yanıtları items ve nextPageToken döndürür — sonraki sayfa için token'ı pageToken olarak geri gönderin (pageSize üst sınırı 500'dür).

Hatalar

Durum	Anlamı	Ne yapmalı
`400`	Doğrulama hatası (eksik `code`/`name`, geçersiz enum değeri, bozuk `locale`)	İşaretlenen alanları düzeltin.
`401`	Eksik veya geçersiz API key	`Authorization: Bearer at_live_…` gönderin.
`404`	Ürün veya çeviri locale'i bulunamadı	`:id`'yi kontrol edin; arşivlenmiş olabilirse `includeArchived=true` ile listeleyin.
`409`	Mükerrer `code`	Ürün kodları merchant başına benzersizdir — başka bir kod seçin veya mevcut ürünü kullanın.

Webhook'lar

Event	Ne zaman
`product.created`	Ürün oluşturuldu.
`product.updated`	Alanlar veya çeviriler değişti.
`product.archived`	Ürün DELETE ile arşivlendi.

Sonraki adımlar

Planlar — bu ürüne fiyat ve faturalama ritmi bağlayın
Pricing & Portal SDK — (çevrilmiş) kataloğu kendi sitenize sunun
Başlarken — ürün → abonelik zincirinin tamamı

Pricing & Portal SDK Planlar