subscription.trial_started

Pairs with member.trial_joined — both fire together when a subscriber starts a trial.

When this fires

A subscriber starts a trial on a trial-enabled plan. Three paths emit it: a cardless trial, an access-code redemption against a trial plan, or a Stripe checkout that begins in a trial window.

Trial checkouts through the other providers (PayPal, Paystack, Razorpay, Skrill, CeyPay, CoinPayments) do not currently emit this event — only Stripe reports the trialing status transition back to Subscriby.

Required ability

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

Payload

The data keys differ by path. Absent keys are omitted entirely, not sent as null.

Cardless trial or access-code redemption

{
  "id": "evt_01HX...",
  "type": "subscription.trial_started",
  "created_at": "2026-05-18T10:05:00Z",
  "api_version": "2026-05-01",
  "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
  "data": {
    "subscription_id": "5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4",
    "plan_id": "c4e82f16-93a7-4d5b-b81c-6e0f27a94d3b",
    "subscriber_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",
    "trial_ends_at": "2026-05-25T10:05:00Z"
  }
}

Stripe checkout starting in a trial

{
  "id": "evt_01HX...",
  "type": "subscription.trial_started",
  "created_at": "2026-05-18T10:05:00Z",
  "api_version": "2026-05-01",
  "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",
  "data": {
    "subscription_id": "5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4",
    "plan_id": "c4e82f16-93a7-4d5b-b81c-6e0f27a94d3b",
    "subscriber_id": "2a91c4e7-6f38-4b52-8e0d-9c1a7b3f5d80",
    "trial_ends_at": "2026-05-25T10:05:00Z",
    "provider": "stripe"
  }
}

Field reference

Field	Type	Notes
`id`	string ULID	Unique event id, prefixed `evt_`. Use for idempotent processing.
`type`	string	Always `subscription.trial_started` 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.subscription_id`	string UUID	Subscription identifier.
`data.plan_id`	string UUID	Plan the trial is on.
`data.subscriber_id`	string UUID	Subscriber's project-scoped user id.
`data.trial_ends_at`	ISO 8601 timestamp, nullable	Present on every path. May be `null` on the Stripe path when the subscription row has no `trial_ends_at` recorded yet — fall back to `GET /v1/subscriptions/{subscription}`.
`data.access_code`	string	Access-code path only. The full redeemed code.
`data.project_id`	string UUID	Access-code path only. Mirrors the envelope `project_id`.
`data.provider`	string	Stripe path only. Always `stripe`.

Caveats

On the cardless-trial and access-code paths this is paired with subscription.created and member.trial_joined for the same subscription_id. On the Stripe path it is paired with subscription.activated instead, and no member.* join event fires.
Plans with trial_days = 0 skip this event entirely.

subscription.trial_converting — fires 24h before trial_ends_at.
subscription.trial_expired — fires if no conversion occurs.
Subscription events overview — back to family overview.