access_code.expired

When this fires

An access code passes its expiry without being redeemed. The placeholder subscription row holding it is hard-deleted immediately after this event is emitted.

Required ability

project-access-code:view — token must carry this at mint time to subscribe an endpoint to this event.

Payload

{
  "id": "evt_01HX...",
  "type": "access_code.expired",
  "created_at": "2026-08-18T00:04:12Z",
  "api_version": "2026-05-01",
  "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
  "data": {
    "plan_id": "c4e82f16-93a7-4d5b-b81c-6e0f27a94d3b",
    "subscription_id": "5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4",
    "expired_at": "2026-08-18T00:00:00Z"
  }
}

Field reference

Field	Type	Notes
`id`	string ULID	Unique event id, prefixed `evt_`. Use for idempotent processing.
`type`	string	Always `access_code.expired` for this event.
`created_at`	ISO 8601 timestamp	Server-side emission time.
`api_version`	string	Webhook API contract version.
`project_id`	string UUID	Project this event belongs to.
`data.plan_id`	string UUID	Plan the code was scoped to.
`data.subscription_id`	string UUID	Placeholder subscription row that held the unredeemed code.
`data.expired_at`	ISO 8601 timestamp	When the code became unredeemable.

The code string itself is not included on this event — only access_code.redeemed carries access_code. The placeholder row referenced by subscription_id is hard-deleted immediately after this event is emitted, so it will not resolve through the API.

Caveats

Expiry is detected by a sweep that runs every five minutes, so created_at trails expired_at by up to five minutes plus queue latency.
Large batches may produce a sustained burst of access_code.expired events when the batch hits its expiry. Plan capacity accordingly.
Codes that were already redeemed do not produce this event regardless of the batch's expires_at.

access_code.redeemed — alternative outcome.
access_code.generated — predecessor (batch-level).
Access code events overview — back to family overview.