Recurring PaymentsSubscriptionsGet Subscription Details

Get Subscription Details

Retrieve one subscription by its numeric ID or subscription_code.

Endpoint

GET https://backendapi.sayswitchgroup.com/api/v1/subscription/{id_or_code}

Request

curl --request GET \
  --url https://backendapi.sayswitchgroup.com/api/v1/subscription/SUB_7q2m9x4k1v8b5n3p6r0s \
  --header "Authorization: Bearer YOUR_SECRET_KEY" \
  --header "Accept: application/json"

{id_or_code} accepts either a numeric subscription ID, such as 84, or a subscription code beginning with SUB_.

Response

{
  "status": true,
  "data": {
    "id": 84,
    "subscription_code": "SUB_7q2m9x4k1v8b5n3p6r0s",
    "return_url": "https://merchant.example/subscription/complete",
    "status": "active",
    "start_at": "2026-10-01T00:00:00.000000Z",
    "next_charge_at": "2026-11-01T00:00:00.000000Z",
    "authorization_expires_at": "2026-09-26T10:30:00.000000Z",
    "authorization_started_at": null,
    "cancelled_at": null,
    "successful_charge_count": 1,
    "metadata": {
      "merchant_order_id": "EMAIL-ORDER-001"
    },
    "domain": "test",
    "plan": {
      "plan_code": "PLN_plan_code",
      "name": "Email Monthly",
      "amount": "15000.00",
      "currency": "NGN",
      "interval": "monthly",
      "invoice_limit": 12,
      "status": "active"
    },
    "customer": {
      "customer_code": "CUS_customer_code",
      "email": "customer@example.com",
      "first_name": "Ada",
      "last_name": "Okafor"
    },
    "payment_method": {
      "payment_method_code": "PM_8r3n1v6q4m9x2k7b5p0s",
      "brand": "mastercard",
      "last4": "0008",
      "exp_month": "01",
      "exp_year": "39",
      "status": "active"
    },
    "invoices": [
      {
        "invoice_code": "INV_3m7q9v2x5k8n1b4p6r0s",
        "transaction_reference": "SUBCHG_7n2m9q4v1x8k5b3p6r0s",
        "amount": "15000.00",
        "currency": "NGN",
        "period_start": "2026-10-01T00:00:00.000000Z",
        "period_end": "2026-11-01T00:00:00.000000Z",
        "due_at": "2026-10-01T00:00:00.000000Z",
        "status": "paid",
        "paid_at": "2026-10-01T00:01:12.000000Z",
        "attempts": [
          {
            "attempt_number": 1,
            "status": "successful",
            "response_code": "00",
            "response_message": "Approved by Financial Institution",
            "attempted_at": "2026-10-01T00:00:10.000000Z"
          }
        ]
      }
    ],
    "authorization_url": null
  }
}

The response can include the plan, customer, masked saved payment method, invoices, and charge attempts. The example shows the merchant-relevant fields and omits internal provider data.

authorization_url is present only while the subscription is pending_authorization. It is null after activation, cancellation, completion, or expiry.

Use the subscription status and webhook events as your source of truth. Do not rely on the browser return URL alone.

Subscription Not Found

HTTP 404:

{
  "status": false,
  "message": "Subscription not found."
}

The same response is returned when the subscription exists under another merchant or test/live environment.

Expired Authorization

When a customer does not authorize before the hosted session expires, the subscription status becomes expired and authorization_url is null. Initialize a new subscription with a new Idempotency-Key if the customer still wants to subscribe.