---
title: "Schedule a downgrade to Trial at the end of the current billing period (admin only)"
method: POST
path: "/api/me/plan/cancel-to-trial"
tags: ["me"]
---

# Schedule a downgrade to Trial at the end of the current billing period (admin only)

`POST /api/me/plan/cancel-to-trial`

## Request

- Base URL: `https://api.signalraven.ai`
- URL: `https://api.signalraven.ai/api/me/plan/cancel-to-trial`
- Auth: none declared

Admin-only Zygnal-side cancel path since Stripe Customer Portal does not list Trial in the plan picker. Schedules the Stripe subscription for cancel-at-period-end and tags subscription.metadata.downgrade_target='trial' so the eventual subscription.deleted webhook flips planId to Trial. Existing credit balance is preserved until period_end (then wiped by the local-expiry cron). No future Trial allotments are granted. PAYG packs survive untouched at their original rate. Idempotent — repeat calls return 409 already_scheduled.

## Response `200`

Cancel-to-Trial scheduled

- CancelToTrialResponse
  - `ok` true, required
  - `effectiveAt` string, date-time, required: ISO timestamp of when the downgrade takes effect (= current period_end). After this date, the customer is on the Trial plan with no auto-allotment; existing credits expire via the local-expiry cron.
  - `subscriptionId` string, required: Stripe subscription id that was scheduled for cancellation.
  - `previousPlanSlug` string, required: Plan slug the customer is downgrading FROM (e.g. "pro"). Used by the portal to render the confirmation.
  - `creditsRemaining` integer, required: Credit balance at the time the downgrade was scheduled. Carries through until effectiveAt.

## Other responses

- `403`: Caller role is not admin
- `404`: Customer not found
- `409`: No active subscription, OR already scheduled to downgrade
- `500`: Stripe API call failed

---

[API](https://skmtc.dev/signalraven/apis/zygnal-api.md) · [All operations](https://skmtc.dev/signalraven/apis/zygnal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signalraven/apis/zygnal-api/revisions/36e1d9b9d604?raw)