# 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](https://kling.is/en/docs/checkout) 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](https://kling.is/en/docs/bank-claims) 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](https://kling.is/en/docs/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).