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 -X PATCH https://api.ikawaari.com/v1/subscriptions/sub_abc123 \
  -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 DELETE https://api.ikawaari.com/v1/subscriptions/sub_abc123 \
  -H "Authorization: Bearer ik_test_your_key"

By default, cancellation takes effect at the end of the current billing period. Set cancel_at_period_end: false for immediate cancellation.