SuperAPI AI Directory

schedules

General & other

View repository

Updated 10-16 07:16

About this skill

Schedules

Schedules

  • A schedule moves a customer between plans over dated phases. Create with createSchedule, preview with previewCreateSchedule.
  • A customer holds ONE schedule. Calling createSchedule again replaces all of it — the old phases and their scheduled plans are deleted. There is no update or delete endpoint.
  • To change a schedule, resend the full phase list, including phases that already started. To drop future phases, resend with only the immediate phase.
  • Plans the schedule never placed (e.g. a separately attached add-on) are always kept.

Phase timing

  • Every phase needs exactly one of starts_at (epoch ms, or "now") or starting_after ({ duration_type: "month" | "year", duration_count }).
  • starts_at: "now" is first-phase only; starting_after is never allowed on the first phase.
  • The first phase must start now. A future first starts_at is rejected. A past one works only for paid recurring plans on a customer with no existing Stripe subscription.
  • starts_at values must be strictly increasing.
  • Quirk: unless you pass billing_cycle_anchor, a later phase starting within 12 hours of the current billing cycle boundary is silently snapped onto that boundary.

Plans in a phase

  • plans: [{ plan_id, entity_id?, feature_quantities?, version?, customize? }].
  • At most one main plan per group and scope per phase; add-ons are exempt.
  • entity_id sets scope: omit it to inherit the request entity, or pass null for customer-level. The first phase fixes the scope — later phases cannot change it.
  • customize here rejects free_trial and license keys. Set a trial at the top level instead.
  • unscheduled_plans bill with the immediate phase and are never expired or replaced by a later phase. It is an error for a phase to claim the same group and scope.

Immediate-phase params

  • free_trial, currency, discounts, invoice_mode, billing_cycle_anchor: "now", and redirect_mode apply only to the immediate phase.
  • free_trial applies to every recurring plan in that phase. on_end: "revert" is not supported on schedules.
  • billing_cycle_anchor: "phase_start" on a later phase resets the Stripe billing cycle when that phase begins.
  • enable_plan_immediately: true grants access while Stripe checkout is still pending. The response returns status: "pending_payment" with a null schedule_id, and the schedule persists once checkout completes.
  • no_billing_changes: true writes the schedule in Autumn without touching Stripe.