KingPay Logokingpay.Documentation
Merchant API
Merchant APISubscriptions

List Subscriptions

Returns a paginated list of all subscriptions associated with your project (API key), ordered from the most recently created to the oldest ones. This behaves similarly to KingPay’s /subscription/list/.

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

All parameters are passed via query string. Results are paginated with up to 50 subscriptions per page, sorted by creation time in descending order.

Notices

  • Only subscriptions belonging to the project identified by the provided apikey are returned.
  • Results are automatically sorted by creation date, newest first.
  • Each subscription entry includes its permanent subscription URL plus a payment_list with invoices that have at least one detected payment.
  • Use the p parameter to navigate between pages. If there are no subscriptions, subscriptions will be an empty array and num_pages will be 0.

Query parameters (required)

apikey string • required

Project API key generated in your merchant dashboard. Identifies which project’s subscriptions will be returned.

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

Query parameters (optional)

p integer • optional

Page number for pagination. Defaults to 1. Each page contains up to 50 subscriptions.

If the provided value is invalid (non-numeric or < 1), it is treated as 1.

Request example (cURL) 
curl -G \
  'https://api-service.kingpay.online/subscription/list/' \
  --data-urlencode 'apikey=YOUR_PROJECT_API_KEY' \
  --data-urlencode 'p=1'
Response (200 • application/json) 
{
  "status": "success",
  "subscriptions": [
    {
      "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
        }
      ]
    }
  ],
  "num_pages": 3
}

Response fields

  • status — request result, usually "success" on a valid request.
  • subscriptions — array of subscription objects for the requested page.
  • num_pages — total number of pages available for the current project (given the fixed page size of 50).

Subscription object

  • token — the same subscription UID returned by creation. Used to identify the subscription on the client side or in other endpoints.
  • url — permanent hosted subscription page URL. Returns null only when the public site URL is not configured.
  • active — subscription status flag (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 (internally the invoiceUid), that can be used as a payment identifier.
  • 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.