Create Subscription

Creates or updates a subscription for a given customer and immediately generates the first payment invoice in fiat. This is ideal for recurring plans where you charge a fixed amount on a regular schedule. Behaves similarly to KingPay’s /subscription/create/, but with an explicit fiat amount, currency, and invoice expiration.

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

All parameters are passed via query string. The response contains a subscription_url (alias: payment_url) that you can show to the user as a hosted checkout page for the first subscription payment.

Notices

An uncancelled subscription is looked up by project + external_id. An active unpaid or partially paid invoice is reused when its amount, currency, interval and plan option match. Changing these terms returns 409 Conflict without updating the subscription. New terms can be applied after the invoice is paid or expires. Creation and public renewal requests are serialized per project.
Each issued invoice retains its original amount, currency and interval, including for late payments. Renewal webhooks describe that invoice's terms. A legacy invoice without a valid saved interval requires manual review; its term is never inferred from the current plan.
The API creates a first invoice of type subscription in pending status, with the specified value in the chosen fiat currency.
The invoice expire_at is a lifetime of 3600 to 604800 seconds (1 hour to 7 days). If omitted, it defaults to 3600.
notify_url is required either as a parameter or via the project’s default ipnCallbackUrl. All IPN callbacks for this invoice (and future renewals) will be sent there.
redirect_url is required either as a parameter or via the project’s default redirect URL. The customer will be sent there after completing the payment, along with the success_token.

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.

value decimal • required

Subscription price in fiat, using the selected currency or the project’s default fiat currency. Must be a positive number.

Example: value=9.99

interval string • required

Subscription billing interval label (for example: day, week, month, three_month, year). This value is stored with the subscription and used by your backend logic to schedule renewals.

customer_email string • required

Customer email address used for notifications and for identifying the subscriber.

Alias: user_email can be used instead of customer_email.

customer_id string • required

User identifier in your system.

Alias: user_id can be used instead of customer_id.

external_id string • required

Unique identifier in your system. Used to link the subscription to your internal user/account record.

Query parameters (optional)

currency string • optional

Fiat currency code used for the value (for example: USD, EUR). If omitted, the project’s default active fiat currency is used.

If neither the parameter nor a project default fiat currency is set, the request will fail.

option string • optional

Subscription plan slug or option code (for example: pro-monthly, starter). Stored in subscription metadata and returned in IPN callbacks, so you can decide what level of access to grant.

item_description string • optional

Human-readable description of what this subscription is for (for example: “Pro plan for user #123”). Intended for your own records or to display in your UI.

notify_url string • optional*

IPN callback URL that will receive all notifications for the first subscription invoice and subsequent renewals.

*Required if the project does not have a default ipnCallbackUrl configured.

redirect_url string • optional*

URL where the user should be redirected after completing the first subscription payment. The success_token can be used on this URL to validate the redirect.

*Required if the project does not have a default redirect URL configured.

expire_at integer • optional

Invoice lifetime in seconds from creation, not a Unix timestamp. Allowed range: 3600–604800; default: 3600.

If omitted, an expiration time of “now + 1 hour” is used.

json integer · optional

json=1 sends callbacks as POST application/json, preserving types and null values for signature verification. Takes precedence over post. Omit both flags for GET; use only post=1 for form-encoded POST.

post integer • optional

post=1 — send IPN callbacks for this subscription using HTTP POST instead of GET. Only the transport changes; the callback parameters remain the same.

Request example (cURL)

curl -G \
  'https://api-service.kingpay.online/subscription/create/' \
  --data-urlencode 'apikey=YOUR_PROJECT_API_KEY' \
  --data-urlencode 'value=9.99' \
  --data-urlencode 'currency=USD' \
  --data-urlencode 'interval=month' \
  --data-urlencode '[email protected]' \
  --data-urlencode 'external_id=USER_123' \
  --data-urlencode 'option=pro-monthly' \
  --data-urlencode 'notify_url=https://example.com/ipn/subscription?user_id=USER_123' \
  --data-urlencode 'redirect_url=https://example.com/account/subscription' \
  --data-urlencode 'post=1'

Response (200 • application/json)

{
  "status": "success",
  "token": "f8ca68e2df97a1d8dc4e0be2974ea0fc",
  "subscription_url": "https://pay.yourdomain.com/pay/f8ca68e2df97a1d8dc4e0be2974ea0fc",
  "payment_url": "https://pay.yourdomain.com/pay/cde7771d47eda69e2d2e8969f781e2f8",
  "success_token": "8c0d3a9b9a1c4f3e8b1d2c3a4f6e7b1f4c0d9a8e1b2c3d4e5f6a7b8c9d0e1f2"
}

Response fields

status — request result, "success" on successful subscription creation/update.
token — subscription token used to identify this subscription in future calls (for example, subscription management, logs, or cancel endpoints).
subscription_url — hosted payment page URL where the user can pay the first subscription invoice.
payment_url — alias of subscription_url, provided for compatibility with code that expects a payment_url field.
success_token — token that can be returned in redirect URLs after a successful payment, allowing your backend to validate that the redirect is legitimate.