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 card 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; checkout.session.completed lists the new subscriptions in data.subscription_ids), 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": "CUSTOMER_ID",
    "product_id": "PRODUCT_ID",
    "payment_method_id": "PAYMENT_METHOD_ID"
  }'

IDs are UUIDs. Without a trial, Kling charges the first period right away. If that first charge is declined, the subscription still shows active and the charge is not retried, so check the payment before you deliver: wait for payment_intent.captured (or payment_intent.failed) with data.subscription_id. Without payment_method_id, a card subscription is never charged.

collection_method is card (default) or bank_claim, which sends an online bank claim each period instead of charging a card. A bank_claim subscription needs payment_method_id of a bank-claim payment method that has the payer's kennitala; without one, no claim is ever sent. Each period's claim is reported with claim.created, then claim.paid and payment_intent.captured when it is paid. subscription.renewed, subscription.payment_failed and automatic retries apply to card subscriptions only.

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

To move a subscription to another product, for example a bigger package, send PATCH /v1/subscriptions/{id} with product_id. The change takes effect at the start of the next period and nothing is prorated: the current period stays as it was charged and the next renewal charges the new product's price. Until then the subscription shows the change in pending_update (product and effective_at). The new product must be an active subscription product in the same currency with the same billing interval. Sending the current product again withdraws the change. The events are subscription.product_change_scheduled when the change is requested and subscription.product_changed when it takes effect.

To charge every subscriber on the same day of the month, set billing_day (1 to 28) on a monthly subscription product. New subscriptions to the product get that day, and you can also set it per subscription with billing_day on POST /v1/subscriptions or PATCH /v1/subscriptions/{id}. The signup payment covers the first period. The first renewal is the first billing day at least first_renewal_min_days days after signup (default 10, 0 turns the rule off), otherwise the one after. With billing_day 5, a subscription created on 17 October renews on 5 November, and one created on 28 October on 5 December. After that it is charged on the billing day every month. Nothing is prorated. Changing a subscription's billing_day takes effect at the next renewal, and a product change keeps the day.

Lifecycle

Status Meaning
trialing In a free trial. Becomes active when the trial ends, just before the first charge; if that charge fails it moves to past_due.
active Paid and renewing.
past_due A card payment failed. Kling is retrying, or billing has stopped until it is fixed.
canceled Ended: after a cancellation, a hard decline, or when every retry failed.

When a card renewal is declined, 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. A card that can never succeed (for example reported lost, or a closed account) cancels the subscription at once, with no retries. If the card processor rejects the charge itself, or can't say whether it went through, billing stops in past_due with no retry until it is resolved.

By default, canceling takes effect at the end of the current period, so the customer keeps what they paid for; the subscription stays active and shows cancel_at_period_end: true until then. To end it right away, send "cancel_immediately": true. The subscription.canceled webhook fires both when the cancellation is requested and when the subscription ends, so check status before you revoke access.

GET /v1/subscriptions/{id} lists the subscription's payments, each with billing_reason subscription_create (the first one) or subscription_cycle (a renewal), so you always know what was charged and why. For which webhooks to handle, note that subscription.renewed covers paid card renewals only: the first charge after a trial arrives as payment_intent.captured with data.subscription_id, and a renewal paid by a retry also sends subscription.payment_recovered.

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": "CUSTOMER_ID", "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).

To let a customer replace the card on a subscription, create the session with subscription set to it. The card they enter in the portal becomes that subscription's card straight away.

To skip the portal and send the customer straight to a card form, create a setup session with subscription set. The customer saves a card on the Kling payment page, it becomes that subscription's card, and they return to your success_url:

bash
curl -X POST https://api.kling.is/v1/payment-methods/setup \
  -H "Authorization: Bearer $KLING_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "CUSTOMER_ID", "subscription": "SUBSCRIPTION_ID", "success_url": "https://example.is/account" }'

Without subscription, a setup session only saves a card on the customer and does not change any subscription.

If the subscription is past_due, the unpaid payment is charged on the new card right away, also when billing has stopped. If it goes through, the subscription returns to active and you receive payment_intent.captured and subscription.payment_recovered. If the new card is declined, you receive payment_intent.failed and the retries continue as before: the decline does not count as a retry and does not cancel the subscription.

View as markdown