Subscription Lifecycle

State Diagram

trialing → active → past_due → unpaid → canceled
              ↘ canceled

Events

Event	Description
subscription.created	New subscription created
subscription.updated	Subscription modified (plan change, etc.)
subscription.trial_will_end	Trial ending in 3 days
invoice.payment_succeeded	Recurring payment successful
invoice.payment_failed	Recurring payment failed
subscription.canceled	Subscription ended

Upgrading / Downgrading

Update the subscription's price to change plans:

curl https://api.ikawaari.com/api/v1/billing/subscriptions/{id} \
  -H "Authorization: Bearer ik_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{ "id": "si_abc123", "price": "price_new_plan" }],
    "proration_behavior": "create_prorations"
  }'

Cancellation

curl -X POST https://api.ikawaari.com/api/v1/billing/subscriptions/{id}/cancel \
  -H "Authorization: Bearer ik_test_your_key"

Detailed subscription updates should not be documented as PATCH until that endpoint appears in the generated reference.