Abonelikler API

Sabit fiyatlı, her dönem yenilenip faturalanan tekrarlayan planlar.

Modül kodu subscriptions · 9 işlem · 2 veri modeli · 9 olay. Bir anahtar ya da token, arkasındaki kişinin bu modülde yapabildiğinden fazlasını asla yapamaz; satır düzeyindeki güvenlik uygulamadakiyle birebir aynıdır. Yetki kapsamları: subscriptions (hepsi), subscriptions:read (yalnız okuma) ya da subscriptions:<yetenek>.

Kaynaklar

Listeler limit (en çok 200), cursor, order (ör. -created_at), fields ve q alır; diğer her sorgu parametresi bir sütun süzgecidir: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

İşlemler

subscriptions.buy_package_online

Online paket satın al — Giriş yapmış müşteri siteden bir paket başlatır: paketin fiyatıyla bir abonelik, ilk dönemi bugünden başlar.

Gereken izin subscriptions:write · veriyi değiştirir · Yayındaki bir siteden de çağrılabilir (customer)

• Asıl adres: POST /api/v1/actions/subscriptions.buy_package_online

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: subscriptions.started, subscriptions.period_started

Neye yazar: subscription (insert) — Starts the subscription; subscription_period (insert) — Opens the first period

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde subscriptions:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 package_not_found, subscription_already_active · 429 çok sık istek

subscriptions.cancel

İptal et — Şimdi ya da ödenmiş dönemin sonunda bitirir.

Gereken izin subscriptions:write · siler ya da geri alınamaz · Era çalıştırırken bir kişiye onaylatır

• Asıl adres: POST /api/v1/actions/subscriptions.cancel

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: subscriptions.cancelled

Neye yazar: subscription (update) — Cancels it; subscription_period (update) — Cancels a period that has not started

curl -X POST https://app.getera.io/api/v1/subscriptions/SUBSCRIPTION_ID/actions/cancel \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"atPeriodEnd":true}'

{
  "ok": true,
  "result": "…",
  "events": [
    "subscriptions.cancelled"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.subscriptions.cancel("SUBSCRIPTION_ID", {
  atPeriodEnd: true
})

era subscriptions cancel SUBSCRIPTION_ID \
  --at-period-end true

{
  "name": "era__subscriptions__cancel",
  "arguments": {
    "id": "SUBSCRIPTION_ID",
    "atPeriodEnd": true
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde subscriptions:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 subscription_not_found, subscription_already_ended · 429 çok sık istek

subscriptions.pause

Duraklat — Aboneliği bitirmeden yenilemeleri durdurur.

Gereken izin subscriptions:write · veriyi değiştirir

• Asıl adres: POST /api/v1/actions/subscriptions.pause

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: subscriptions.paused

Neye yazar: subscription (update) — Pauses it

curl -X POST https://app.getera.io/api/v1/subscriptions/SUBSCRIPTION_ID/actions/pause \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "subscriptions.paused"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.subscriptions.pause("SUBSCRIPTION_ID")

era subscriptions pause SUBSCRIPTION_ID

{
  "name": "era__subscriptions__pause",
  "arguments": {
    "id": "SUBSCRIPTION_ID"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde subscriptions:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 subscription_not_found, subscription_not_active · 429 çok sık istek

subscriptions.raise_ending_notices

“Yakında bitiyor” bildirimlerini oluştur — Günlük iş: yenilenmeyecek ve süre içinde bitecek her abonelik dönem başına bir kez bildirilir.

Gereken izin subscriptions:write · veriyi değiştirir

• Asıl adres: POST /api/v1/actions/subscriptions.raise_ending_notices

Girdi

Yayımladığı olaylar: subscriptions.ending_soon

Neye yazar: subscription (update) — Records that the ending notice was raised

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde subscriptions:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 429 çok sık istek

subscriptions.renew

Şimdi yenile — Sonraki dönemi açar — ya da süresi veya iptali öyle diyorsa aboneliği bitirir.

Gereken izin subscriptions:write · veriyi değiştirir

• Asıl adres: POST /api/v1/actions/subscriptions.renew

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: subscriptions.renewed, subscriptions.period_started, subscriptions.cancelled, subscriptions.expired

Neye yazar: subscription (update) — Moves it onto the next period; subscription_period (insert) — Opens the period

curl -X POST https://app.getera.io/api/v1/subscriptions/SUBSCRIPTION_ID/actions/renew \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "subscriptions.renewed",
    "subscriptions.period_started",
    "subscriptions.cancelled",
    "subscriptions.expired"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.subscriptions.renew("SUBSCRIPTION_ID")

era subscriptions renew SUBSCRIPTION_ID

{
  "name": "era__subscriptions__renew",
  "arguments": {
    "id": "SUBSCRIPTION_ID"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde subscriptions:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 subscription_not_found, subscription_not_renewable · 429 çok sık istek

subscriptions.renew_due

Yenileme zamanı gelenleri yenile — Yenileme tarihi gelen her otomatik aboneliği yeniler.

Gereken izin subscriptions:manage · veriyi değiştirir

• Asıl adres: POST /api/v1/actions/subscriptions.renew_due

Girdi

Yayımladığı olaylar: subscriptions.renewed, subscriptions.period_started, subscriptions.cancelled, subscriptions.expired

Neye yazar: subscription (update) — Moves each onto its next period; subscription_period (insert) — Opens the periods

curl -X POST https://app.getera.io/api/v1/subscription_periods/actions/renew_due \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"asOf":"2026-11-02"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "subscriptions.renewed",
    "subscriptions.period_started",
    "subscriptions.cancelled",
    "subscriptions.expired"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.subscriptionPeriods.renewDue({
  asOf: "2026-11-02"
})

era subscription_periods renew_due \
  --as-of "2026-11-02"

{
  "name": "era__subscriptions__renew_due",
  "arguments": {
    "asOf": "2026-11-02"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde subscriptions:manage izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 429 çok sık istek

subscriptions.resume

Devam ettir — Duraklatılmış aboneliği yeniden başlatır; sonraki yenileme en erken bugündür.

Gereken izin subscriptions:write · veriyi değiştirir

• Asıl adres: POST /api/v1/actions/subscriptions.resume

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: subscriptions.resumed

Neye yazar: subscription (update) — Resumes it

curl -X POST https://app.getera.io/api/v1/subscriptions/SUBSCRIPTION_ID/actions/resume \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

{
  "ok": true,
  "result": "…",
  "events": [
    "subscriptions.resumed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.subscriptions.resume("SUBSCRIPTION_ID")

era subscriptions resume SUBSCRIPTION_ID

{
  "name": "era__subscriptions__resume",
  "arguments": {
    "id": "SUBSCRIPTION_ID"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde subscriptions:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 subscription_not_found, subscription_not_paused · 429 çok sık istek

subscriptions.set_auto_renew

Yenileme — Dönem bittiğinde kendiliğinden yenilenip yenilenmeyeceği; yenilenmeyen abonelik günlük kontrolde sonlandırılır.

Gereken izin subscriptions:write · veriyi değiştirir

• Asıl adres: POST /api/v1/actions/subscriptions.set_auto_renew

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: subscriptions.auto_renew_changed

Neye yazar: subscription (update) — Sets auto_renew

curl -X POST https://app.getera.io/api/v1/subscriptions/SUBSCRIPTION_ID/actions/set_auto_renew \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"autoRenew":true}'

{
  "ok": true,
  "result": "…",
  "events": [
    "subscriptions.auto_renew_changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.subscriptions.setAutoRenew("SUBSCRIPTION_ID", {
  autoRenew: true
})

era subscriptions set_auto_renew SUBSCRIPTION_ID \
  --auto-renew true

{
  "name": "era__subscriptions__set_auto_renew",
  "arguments": {
    "id": "SUBSCRIPTION_ID",
    "autoRenew": true
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde subscriptions:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 subscription_not_found, subscription_already_ended · 429 çok sık istek

subscriptions.start

Abonelik başlat — Sabitlenmiş fiyatla tekrarlayan bir dönem. İlk dönem şimdi ya da deneme bitince açılır.

Gereken izin subscriptions:write · veriyi değiştirir

• Asıl adres: POST /api/v1/actions/subscriptions.start

Girdi

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Yayımladığı olaylar: subscriptions.started, subscriptions.period_started

Neye yazar: subscription (insert) — Starts the subscription; subscription_period (insert) — Opens the first period

curl -X POST https://app.getera.io/api/v1/subscriptions/actions/start \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"customerId":"CUSTOMER_ID","name":"Plan","amount":1}'

{
  "ok": true,
  "result": "…",
  "events": [
    "subscriptions.started",
    "subscriptions.period_started"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.subscriptions.start({
  customerId: "CUSTOMER_ID",
  name: "Plan",
  amount: 1
})

era subscriptions start \
  --customer-id "CUSTOMER_ID" \
  --name "Plan" \
  --amount 1

{
  "name": "era__subscriptions__start",
  "arguments": {
    "customerId": "CUSTOMER_ID",
    "name": "Plan",
    "amount": 1
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde subscriptions:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 customer_not_found, customer_archived, invalid_currency, subscription_amount_not_positive, subscription_already_active, subscription_end_before_start · 429 çok sık istek

Veri modelleri

SubscriptionPeriod

Tablo subscription_period · Kaynak subscription_periods

• GET /api/v1/subscription_periods
• GET /api/v1/subscription_periods/{id}

Birincil anahtar: id

Tekil: subscription_id, sequence

Denetimler:

• CHECK ((amount >= 0))
• CHECK ((currency ~ '^[A-Z]{3}$'::text))
• CHECK ((period_end >= period_start))
• CHECK ((sequence > 0))

Subscription

Tablo subscription · Kaynak subscriptions

• GET /api/v1/subscriptions
• GET /api/v1/subscriptions/{id}

Birincil anahtar: id

Denetimler:

• CHECK ((amount >= 0))
• CHECK ((currency ~ '^[A-Z]{3}$'::text))
• CHECK (((end_date IS NULL) OR (end_date >= start_date)))
• CHECK ((length(TRIM(BOTH FROM name)) > 0))
• CHECK (((period_months IS NULL) OR (period_months > 0)))
• CHECK ((renewals >= 0))

Olaylar

İş akışları ve webhook'lar bu olaylara tepki verir.