Topics

DocsTake payments

Subscriptions and the billing portal

Charge customers in Iceland automatically every week, month or year with Kling subscriptions, retry failed payments and let customers manage their own subscription in the billing portal.

A subscription connects a customer to a recurring product and charges them automatically every period. Kling retries failed payments and keeps a record of every charge. Customers manage their own subscription in the billing portal.

Without code

  1. In the dashboard, open Products and create a subscription product with a price and a billing interval (week, month or year), and a free trial if you want one.
  2. Open Payment Links and create a link with that product. That is your subscription link.
  3. Share it. The customer signs up and pays the first period by card, and Kling charges the saved card at the start of each new period.

With the API

Create a product, then either send the customer through a checkout session with that product_id (they enter their card and the subscription starts), or create the subscription directly for a customer who already has a saved card:

bash
curl -X POST https://api.kling.is/v1/subscriptions \
  -H "Authorization: Bearer $KLING_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_...",
    "product_id": "prod_...",
    "payment_method_id": "pm_..."
  }'

collection_method is card (default) or bank_claim, which sends an online bank claim each period instead of charging a card.

Other endpoints: POST /v1/subscriptions/{id}/cancel, POST /v1/subscriptions/{id}/reactivate, and POST or DELETE /v1/subscriptions/{id}/discount.

Lifecycle

Status Meaning
trialing In a free trial. Becomes active when the first payment succeeds.
active Paid and renewing.
past_due A renewal payment failed and Kling is retrying.
canceled Ended, after a cancellation or when every retry failed.

When a renewal fails, Kling retries 1, 3 and 7 days after each previous attempt (three retries). If a retry succeeds the subscription goes back to active; if all fail it is canceled.

By default, canceling takes effect at the end of the current period, so the customer keeps what they paid for; the subscription shows cancel_at_period_end: true until then. To end it right away, send "cancel_immediately": true.

Each charge is a payment with billing_reason subscription_create (the first one) or subscription_cycle (a renewal), so you always know what was charged and why. The subscription.renewed, subscription.payment_failed and subscription.canceled webhooks tell your server what happened.

Billing portal

The billing portal is a page where your customer can see their subscription and recent payments, update their card, cancel and reactivate. Create a portal session and send the customer to its url:

bash
curl -X POST https://api.kling.is/v1/billing-portal/sessions \
  -H "Authorization: Bearer $KLING_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customer": "cus_...", "return_url": "https://example.is/account" }'

Options: subscription (limit it to one subscription), allow_cancel and allow_update_payment_method (both on by default), and expires_in in seconds (default 1800).

View as markdown