`subscription.renewal_overdue`

Fired when a prepaid subscription's period_end passed without renewal.

When it fires

QuotaStack sends this when a prepaid period ends and nobody called renew. The grace period starts here. A QuotaStack job raises it.

When it does not fire

QuotaStack does not send this for a postpaid subscription. QuotaStack does not send it once the grace period runs out. subscription.expired covers that.

data

Field	Type	Meaning
`id`required	string (uuid)
`tenant_id`required	string (uuid)
`customer_id`required	string (uuid)
`plan_variant_id`required	string (uuid)
`environment`required	string	`live` `sandbox` Which environment this resource lives in. Determined by the API key prefix used (`qs_live_…` → live, `qs_test_…` → sandbox).
`status`required	string	`trialing` `active` `cancelling` `canceled` `expired` `paused` `overdue` `contract_ended`
`origin`optional	string	`api` `import` How the subscription was created — `api` (normal create) or `import` (legacy cutover).
`started_at`required	string (date-time)
`trial_ends_at`optional	string (date-time)
`current_period_start`optional	string (date-time)
`current_period_end`optional	string (date-time)
`billing_anchor`optional	integer	Day of month (1-28) for monthly renewals.
`cancel_at_period_end`required	boolean
`scheduled_variant_id`optional	string (uuid)
`external_subscription_id`optional	string
`paused_at`optional	string (date-time)
`resumed_at`optional	string (date-time)
`expired_at`optional	string (date-time)
`contract_start`optional	string (date-time)
`contract_end`optional	string (date-time)
`contract_ending_soon_days`required	integer
`metadata`required	object
`created_at`required	string (date-time)
`updated_at`required	string (date-time)

Example payload

{
  "event_id": "0192f5a4-7c31-7b8e-9a2d-4f6c8e1b3a51",
  "event_type": "subscription.renewal_overdue",
  "tenant_id": "0192f5a4-7c31-7b8e-9a2d-4f6c8e1b3a01",
  "environment": "live",
  "customer_id": "0192f5a4-7c31-7b8e-9a2d-4f6c8e1b3a05",
  "external_customer_id": "user_42",
  "created_at": "2026-08-01T00:00:00Z",
  "idempotency_key": "sub-overdue:0192f5a4-7c31-7b8e-9a2d-4f6c8e1b3a21",
  "data": {
    "id": "0192f5a4-7c31-7b8e-9a2d-4f6c8e1b3a21",
    "plan_variant_id": "0192f5a4-7c31-7b8e-9a2d-4f6c8e1b3a12",
    "status": "overdue",
    "current_period_end": "2026-08-01T00:00:00Z"
  }
}

What to do

Chase the money while the grace period lasts. The customer can still work, by default.

Which calls fire this

QuotaStack's scheduler, on a timer — no API call involved.

Delivery

QuotaStack guarantees at-least-once delivery. An event may be delivered more than once if your endpoint returns a non-2xx response, the connection fails, or the request exceeds the delivery timeout.

Delivery timeout: 5 seconds per attempt. If your endpoint does not return a 2xx within 5 seconds, the attempt is treated as a failure and retried. Not configurable today.

One webhook URL per tenant. Multiple URLs and per-event routing are not supported. Configure the URL via the tenant config endpoint.

Retry schedule

If delivery fails (non-2xx response, timeout, or network error), QuotaStack retries with exponential backoff:

Attempt	Delay after previous
1	Immediate
2	30 seconds
3	5 minutes
4	30 minutes
5	2 hours
6	8 hours
7	24 hours

After 7 failed attempts, the event is moved to a dead letter queue. Dead-lettered events are not lost — you can requeue them yourself, from the dashboard (Activity → Webhooks → Redeliver) or the API:

curl -X POST https://api.quotastack.io/v1/webhooks/events/{event_id}/redeliver \
  -H "X-API-Key: $QS_KEY" \
  -H "Idempotency-Key: redeliver:{event_id}"

Redelivery resets the event to pending with a fresh retry schedule (7 new attempts). The next attempt signs with your current secret — useful when the event dead-lettered because of a secret rotation or an endpoint outage you have since fixed. Only dead_letter events can be redelivered; the call returns 409 for events in any other status.

Handling duplicates

Because delivery is at-least-once, your webhook handler should be idempotent. Use the webhook-id header for deduplication — if you have already processed an event with that ID, return 200 and skip processing.

● raw markdown · subscription.renewal_overdue.md ↗ — this is exactly what an agent fetches

Loading…

subscription.renewal_overdue