retrieve-subscriptions

POST /api/{team}/gateway/retrieve-subscriptions

Aboneliklerin güncel hâlini döndürür; hiçbir şeyi değiştirmez. Her abonelik içinde bulunulan dönemi (renewal) ve kendi customer alanıyla döner.

Kimlik doğrulama

X-Api-Key, X-Timestamp, X-Signature, Content-Type: application/json. Ayrıntılar: Kimlik Doğrulama ve İmza.

İstek

Kayıt üç yoldan biriyle adlandırılır; en fazla biri gönderilir:

{ "token": "3b7e1f20-5c4a-4d8e-9f1b-7a6c5d4e3f21" }

{ "reference": "SIP-10233" }

{ "created_from": "2026-09-26", "created_to": "2026-10-02" }

Alan	Tip	Zorunlu	Açıklama
`token`	string (UUID)	hayır	Kaydın token'ı. `reference` ya da tarih aralığıyla birlikte gönderilmez.
`reference`	string	hayır	Aboneliğin referansı. Tarih aralığıyla birlikte gönderilmez. Bu referansla açılmış aboneliklerin hepsi döner.
`created_from`	string	hayır	Başlangıç günü, `YYYY-MM-DD`. `created_to` ile birlikte gönderilir.
`created_to`	string	hayır	Bitiş günü, `YYYY-MM-DD`. `created_from` ile birlikte gönderilir; ondan önce olamaz. Aralık iki gün dahil en fazla 7 gündür.

Tarihler çalışma alanının saat dilimindedir. Hiçbir alan gönderilmezse ({}) bugün dahil son 7 gün listelenir. Yanıt her zaman bir listedir; eşleşen kayıt yoksa liste boştur. Başka bir çalışma alanının kaydı hiçbir zaman dönmez.

reference tekil değildir: aynı referansla yapılan her create-subscription çağrısı ayrı bir abonelik açar. reference ile sorgu bu aboneliklerin hepsini, eskiden yeniye döndürür; aralarından istediğinizi token ve status ile ayırt edin. Tek bir aboneliği kesin olarak sorgulamak için create-subscription yanıtında aldığınız token gönderilir.

SDK örnekleri

not

Örneklerdeki $client / client nesnesinin kurulumu: İstemciyi Kurmak.

PHP
Node.js
Python
Java
cURL

use Gurmehub\Odemehub\Request\RetrieveSubscriptions;

$subscription = $client->retrieveSubscriptions(RetrieveSubscriptions::byToken($subscriptionToken))->subscriptions[0] ?? null;

$subscription?->status;            // Enum\SubscriptionStatus
$subscription?->renewal->paidAt;
$subscription?->nextPaymentAt;

const [subscription] = (await client.retrieveSubscriptions({ token: subscriptionToken })).subscriptions;

subscription?.status;          // pending | active | past_due | cancelled | completed
subscription?.renewal.paidAt;
subscription?.nextPaymentAt;

from odemehub.request import RetrieveSubscriptions

subscriptions = client.retrieve_subscriptions(RetrieveSubscriptions(token=subscription_token)).subscriptions

if subscriptions:
    subscriptions[0].status
    subscriptions[0].renewal.paid_at
    subscriptions[0].next_payment_at

import com.odemehub.request.RetrieveSubscriptions;

var subscriptions = client.retrieveSubscriptions(RetrieveSubscriptions.byToken(subscriptionToken)).getSubscriptions();

if (!subscriptions.isEmpty()) {
    subscriptions.get(0).getStatus();
    subscriptions.get(0).getRenewal().getPaidAt();
    subscriptions.get(0).getNextPaymentAt();
}

URI_PATH="/api/$ODEMEHUB_TEAM/gateway/retrieve-subscriptions"
BODY='{"reference":"ABO-1"}'
TIMESTAMP=$(date +%s)
SIGNATURE=$(printf '%s\n%s\n%s\n%s' "$TIMESTAMP" "POST" "$URI_PATH" "$BODY" | openssl dgst -sha256 -hmac "$ODEMEHUB_API_SECRET" | sed 's/^.* //')

curl -X POST "https://sandbox.odemehub.com$URI_PATH" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $ODEMEHUB_API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  --data-raw "$BODY"

Yanıt

İlk dönemi HOSGELDIN kuponuyla ödenmiş bir abonelik:

{
  "result": { "successful": true, "message": null },
  "subscriptions": [
    {
      "token": "5e7a9c1d-3f2b-4d6e-8a0c-2b4d6f8a0c1e",
      "reference": "ABO-1",
      "description": null,
      "payment_provider_token": null,
      "status": "active",
      "period": "monthly",
      "renewal_limit": 12,
      "renewals_paid": 1,
      "items": [
        { "reference": null, "name": "Premium", "image": null, "quantity": 1, "unit_amount": "99.90", "tax_rate": "20.00" }
      ],
      "shipping_method": null,
      "discount": { "code": "HOSGELDIN", "amount": "20.00" },
      "subtotal": "83.25",
      "shipping_amount": "0.00",
      "tax_amount": "16.65",
      "amount": "99.90",
      "currency": "TRY",
      "is_test": false,
      "renewal": {
        "token": "9a1c3e5f-7b2d-4f6a-8c0e-1d3f5a7c9e2b",
        "amount": "79.90",
        "currency": "TRY",
        "starts_at": "2026-10-02T10:00:00.000000Z",
        "ends_at": "2026-11-02T10:00:00.000000Z",
        "paid_at": "2026-10-02T10:00:00.000000Z"
      },
      "next_payment_at": "2026-11-02T10:00:00.000000Z",
      "cancelled_at": null,
      "created_at": "2026-10-02T09:55:00.000000Z",
      "checkout_url": null,
      "customer": {
        "reference": "musteri-88",
        "billing_address": { "firstname": "Ahmet", "lastname": "Yılmaz", "email": "[email protected]" },
        "shipping_address": null
      }
    }
  ]
}

Alan	Tip	Açıklama
`created_from`, `created_to`	string	Yalnızca tarih aralığıyla (ya da boş gövdeyle) sorulduğunda: listenin kapsadığı günler.
`subscriptions[]`	array	Abonelik nesneleri, her biri `customer` alanıyla; eskiden yeniye.

Abonelik nesnesi

create-subscription, update-subscription yanıtlarında ve bu listede aynı nesne döner.

Alan	Tip	Açıklama
`token`	string	Aboneliğin token'ı.
`reference`	string	Aboneliğin referansı. Tekil değildir; aynı referansla birden çok abonelik olabilir.
`description`	string \| null	Açıklama.
`payment_provider_token`	string \| null	İstekte verilen ödeme hesabı; verilmediyse `null`.
`status`	string	`pending`, `active`, `past_due`, `cancelled`, `completed`. Aşağıya bakın.
`period`	string	`daily`, `weekly`, `monthly`, `annually`.
`renewal_limit`	integer \| null	Alınacak toplam dönem ödemesi sayısı; sınırsızsa `null`.
`renewals_paid`	integer	Şimdiye kadar ödenen dönem sayısı.
`items[]`, `shipping_method`		Sipariş nesnesindeki gibi.
`discount`	object \| null	İlk dönemin ödemesinde ödeme sayfasında uygulanan kupon: `code`, `amount` (kalemlerden düşülen tutar, aboneliğin para biriminde). Kupon yoksa `null`. Kupon yalnızca ilk dönemde uygulanır. Bkz. Kupon ve `discount`.
`subtotal`, `shipping_amount`, `tax_amount`, `amount`	string	Aboneliğin güncel kalemlerine göre bir dönemin tutarları; Sipariş nesnesindeki gibi. Gönderim ücreti yalnızca ilk dönemde alınır. Kupon indirimi bu tutarlardan düşülmez; ilk dönem için çekilen indirimli tutar, ilk dönemin `renewal.amount` alanındadır.
`currency`	string	Para birimi.
`is_test`	boolean \| null	İlk ödemeden önce `null`; sonra ilk ödemenin test modunda alınıp alınmadığı.
`renewal`	object	İçinde bulunulan (en son) dönem.
`renewal.token`	string	Dönemin token'ı; `checkout_url` bu token'la kurulur.
`renewal.amount`, `renewal.currency`	string	Dönemin tutarı ve para birimi. İlk dönemde kupon ve gönderim ücreti bu tutara yansır.
`renewal.starts_at`, `renewal.ends_at`	string \| null	Dönemin başlangıcı ve sonu, ISO 8601 UTC. Dönem ödenmeden `null`.
`renewal.paid_at`	string \| null	Dönemin ödendiği an; ödenmediyse `null`.
`next_payment_at`	string \| null	Bir sonraki dönem ödemesinin müşterinin varsayılan kartından çekileceği an. İlk ödemeden önce, iptalden sonra ve son dönemde `null`.
`cancelled_at`	string \| null	İptal anı; iptal edilmediyse `null`.
`created_at`	string	ISO 8601 UTC.
`checkout_url`	string \| null	İçinde bulunulan dönemin ödeme sayfası. Dönem ödenmemişken ve abonelik `cancelled` ya da `completed` değilken dolu; değilse `null`.

`status`	Anlamı
`pending`	Abonelik açıldı, ilk dönem henüz ödenmedi.
`active`	Son dönem ödendi. İptal edilmiş ama ödenmiş dönemi süren abonelik de dönem sonuna kadar `active` kalır (`cancelled_at` dolu).
`past_due`	Bir dönem ödemesi kayıtlı karttan alınamadı; dönem `checkout_url` üzerinden ödenebilir.
`cancelled`	İptal edildi ve sona erdi.
`completed`	`renewal_limit` kadar dönem ödendi ve son dönem bitti.

Listedeki her aboneliğin customer alanı: Yanıttaki customer.

HTTP durum kodları

Kod	Durum
`200`	Liste döndü; eşleşen kayıt yoksa boş.
`401`	API anahtarı ya da imza geçersiz.
`403`	Çalışma alanı işlem yapamıyor, planı abonelikleri kapsamıyor ya da Abonelik modülü kapalı.
`422`	Doğrulama hatası.
`429`	İstek sınırı aşıldı.

Hatalar

Alan	Mesaj
`token`	`Token ile birlikte referans ya da tarih aralığı gönderilmez.`
`reference`	`Referans ile birlikte tarih aralığı gönderilmez.`
`created_to`	`Bitiş tarihi başlangıç tarihinden önce olamaz.` / `Tarih aralığı en fazla 7 gün olabilir.`

Kimlik doğrulama​

İstek​

SDK örnekleri​

Yanıt​

Abonelik nesnesi​

HTTP durum kodları​

Hatalar​