Fetch Subscription

Fetches a single subscription by its token and returns all related payment information, including the latest payment URL and the full payment history. Behaves similarly to KingPay’s /subscription/fetch/.

GET https://api-service.kingpay.online/subscription/fetch/

All parameters are passed via query string. You must provide a valid apikey and a subscription token, as returned by the /subscription/create/ or /subscription/list/ endpoints.

Notices

If the token does not belong to the project identified by apikey, the endpoint returns 404 Subscription not found.
The url field points to the permanent subscription page, including before the first payment and after an invoice expires.
The payment_list includes only invoices with detected payments, ordered by invoice creation date, newest first.
duration_ts is derived from the invoice’s saved interval and is the same for all payments of this subscription.

Query parameters (required)

apikey string • required

Project API key generated in your merchant dashboard. Identifies which project this subscription belongs to.

May be sent either as a query parameter or via the apikey HTTP header.

token string • required

Subscription token you received when creating the subscription (field token in /subscription/create/) or from the subscriptions[].token field in /subscription/list/.

This is the same subscription UID returned by the create and list endpoints.

Query parameters (optional)

This endpoint does not accept any optional query parameters beyond apikey and token.

Request example (cURL)

curl -G \
  'https://api-service.kingpay.online/subscription/fetch/' \
  --data-urlencode 'apikey=YOUR_PROJECT_API_KEY' \
  --data-urlencode 'token=sub_0a3f1c9b84e7d2a1f5c9b3e7d1a4f8c2'

Response (200 • application/json)

{
  "status": "success",
  "subscription": {
    "token": "sub_0a3f1c9b84e7d2a1f5c9b3e7d1a4f8c2",
    "url": "https://pay.yourdomain.com/subscription/sub_0a3f1c9b84e7d2a1f5c9b3e7d1a4f8c2",
    "active": true,
    "user_id": "USER_123",
    "user_email": "[email protected]",
    "end_date_ts": 1753022709,
    "payment_list": [
      {
        "token": "4f1c9b84e7d2a1f5c9b3e7d1a4f8c2b3",
        "value": "9.99",
        "coin": "usd",
        "duration_ts": 2592000,
        "received_fiat": "9.99",
        "is_paid": true,
        "is_pending": false,
        "is_partial": false
      }
    ]
  }
}

Response fields

status — request result, usually "success" on a valid request.
subscription — subscription object corresponding to the provided token.

Subscription object

token — the subscription UID returned by creation. Can be used in other subscription-related endpoints.
url — permanent hosted subscription page URL. Returns null only when the public site URL is not configured.
active — true if the subscription is currently active.
user_id — value of the original external_id / user_id used when creating the subscription.
user_email — customer e-mail address used for this subscription.
end_date_ts — Unix timestamp (seconds) of the current subscription period end (nextBillingAt), or null if no period is set. It is not the cancellation timestamp.
payment_list — invoices with at least one detected payment, sorted by invoice creation date (newest first). Includes pending, partial and paid entries; empty invoices are omitted.

Payment object (inside payment_list)

token — invoice token (internal invoiceUid) that identifies this specific subscription payment.
value — invoice amount in fiat, as a string.
coin — fiat currency code (for example: usd, eur), lower-cased.
duration_ts — the invoice's saved nominal interval duration in seconds: day = 1 day, week = 7 days, month = 30 days, three_month = 90 days, year = 365 days; null for an unknown interval. Renewal dates follow calendar intervals, so actual month and year lengths can differ.
received_fiat — sum of confirmed and completed incoming payments in fiat, before fees, as a decimal string. Pending, invalid and refunded payments do not contribute. Returns "0" if none qualify, or null if any qualifying payment has no known fiat value. Distribution does not count the same payment again.
is_paid — true if the invoice is fully paid.
is_pending — true if an incoming payment for this invoice is awaiting blockchain confirmations. An unpaid invoice without a detected payment has false.
is_partial — true if the invoice is partially paid.