Skip to main content

Milestone 5.2e — Subscription renew, cancel, and rollover

Status: Shipped (preview)
Tracking: ehx-api#15

API​

MethodPathPurpose
GET/api/v1/account/subscriptionActive subscription snapshot
POST/api/v1/account/subscription/cancel{ "cancel_at_period_end": true | false }
POST/api/v1/account/subscription/reactivateClear cancel-at-period-end

Processor webhooks (same HMAC as settlement) on POST /api/v1/checkout/webhooks/settlement:

  • subscription.renewed + subscription_id → extend period
  • subscription.canceled + subscription_id → cancel (optional cancel_at_period_end)

Plan API fields​

GET /api/v1/account/plan includes:

  • renewal_ends_at — period end
  • current_period_start
  • cancel_at_period_end
  • subscription_id

Background rollover​

EHX_SUBSCRIPTION_RENEW_LOOP_ENABLED=1 (default) runs every EHX_SUBSCRIPTION_RENEW_INTERVAL_SEC (default 120s):

  • Past current_period_end + cancel_at_period_end → status=canceled
  • Past end + EHX_SUBSCRIPTION_AUTO_RENEW_STUB=1 → extend period (dev only)
  • Else → status=expired (requires new checkout payment)

Analytics: subscription_renewed, subscription_cancel_scheduled, subscription_expired via site_events.

Web​

  • /account/plan — cancel / reactivate panel
  • Requires sign-in cookie or session for subscription APIs; principal-scoped subs work with Authorization + linked principal