subscription.imported
Subscription imported via legacy cutover.
When it fires
QuotaStack sends this when an import makes a subscription, and only when the import asks for events. The dates are the ones you sent, not a fresh cycle.
When it does not fire
QuotaStack sends nothing when emit_webhooks is left out. QuotaStack never sends subscription.created for an import, whatever you set. A handler that sets accounts up on that event alone will skip every customer you move over. credit.granted is off for imports too. The credits you seed arrive quietly.
| Field | Type | Meaning |
|---|---|---|
idrequired | string (uuid) | |
tenant_idrequired | string (uuid) | |
customer_idrequired | string (uuid) | |
plan_variant_idrequired | string (uuid) | |
environmentrequired | string |
Which environment this resource lives in. Determined by the API key prefix used ( |
statusrequired | string |
|
originoptional | string |
How the subscription was created — |
started_atrequired | string (date-time) | |
trial_ends_atoptional | string (date-time) | |
current_period_startoptional | string (date-time) | |
current_period_endoptional | string (date-time) | |
billing_anchoroptional | integer | Day of month (1-28) for monthly renewals. |
cancel_at_period_endrequired | boolean | |
scheduled_variant_idoptional | string (uuid) | |
external_subscription_idoptional | string | |
paused_atoptional | string (date-time) | |
resumed_atoptional | string (date-time) | |
expired_atoptional | string (date-time) | |
contract_startoptional | string (date-time) | |
contract_endoptional | string (date-time) | |
contract_ending_soon_daysrequired | integer | |
metadatarequired | object | |
created_atrequired | string (date-time) | |
updated_atrequired | string (date-time) |
{
"event_id": "0192f5a4-7c31-7b8e-9a2d-4f6c8e1b3a51",
"event_type": "subscription.imported",
"tenant_id": "0192f5a4-7c31-7b8e-9a2d-4f6c8e1b3a01",
"environment": "live",
"customer_id": "0192f5a4-7c31-7b8e-9a2d-4f6c8e1b3a05",
"external_customer_id": "user_42",
"created_at": "2026-07-28T09:00:00Z",
"idempotency_key": "import-sub:user_42",
"data": {
"id": "0192f5a4-7c31-7b8e-9a2d-4f6c8e1b3a21",
"plan_variant_id": "0192f5a4-7c31-7b8e-9a2d-4f6c8e1b3a12",
"status": "active",
"current_period_start": "2026-07-01T00:00:00Z",
"current_period_end": "2026-08-01T00:00:00Z"
}
}What to do
Handle this event next to subscription.created. Or run the cutover quietly, and set the accounts up from your own script.
Which calls fire this
See also
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.
Loading…