Skip to content

Billing API (Stripe Connect)

Standalone products use Stripe Connect for billing. Each product has its own connected Stripe account with independent pricing, invoices, and customer management.

Endpoints

All billing endpoints require:

  • Authorization: Bearer <access_token> (from headless auth)
  • X-Product-Slug header (identifies the product)

Create Checkout Session

Redirects the user to Stripe Checkout to subscribe.

curl -X POST https://kiket.dev/api/v1/billing/checkout_session \
  -H "Authorization: Bearer eyJ..." \
  -H "X-Product-Slug: spravce-gdpr" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_tier": "team",
    "success_url": "https://spravce-gdpr.cz/billing/success?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://spravce-gdpr.cz/billing/cancel"
  }'

Response:

{
  "checkout_url": "https://checkout.stripe.com/c/pay/cs_...",
  "session_id": "cs_test_..."
}

Plan tiers: solo, team, agency, enterprise.

Get Subscription Status

curl https://kiket.dev/api/v1/billing/subscription \
  -H "Authorization: Bearer eyJ..." \
  -H "X-Product-Slug: spravce-gdpr"

Response:

{
  "subscription": {
    "id": 42,
    "plan_tier": "team",
    "status": "active",
    "trial_ends_at": null,
    "current_period_start": "2026-04-01T00:00:00Z",
    "current_period_end": "2026-05-01T00:00:00Z",
    "canceled_at": null,
    "can_use_features": true
  }
}

Customer Portal

Opens Stripe's billing portal for the customer to manage their subscription.

curl -X POST https://kiket.dev/api/v1/billing/portal_session \
  -H "Authorization: Bearer eyJ..." \
  -H "X-Product-Slug: spravce-gdpr" \
  -H "Content-Type: application/json" \
  -d '{ "return_url": "https://spravce-gdpr.cz/billing" }'

Stripe Webhooks

Configure your Stripe Connect webhook to point to:

POST https://kiket.dev/api/v1/billing/stripe_webhook

Set the STRIPE_CONNECT_WEBHOOK_SECRET environment variable. Kiket handles:

  • customer.subscription.created/updated — activates/updates ProductSubscription
  • customer.subscription.deleted — cancels ProductSubscription
  • invoice.paid — activates subscription on first payment
  • invoice.payment_failed — marks subscription as past_due

Subscription Statuses

Status Description
trialing Free trial (14 days default)
active Paying subscription
past_due Payment failed, retrying
canceled Subscription canceled
expired Trial or subscription ended

can_use_features is true only for trialing and active.