create_plan

Create a new subscription plan on a project. Requires at least one linked project resource.

Purpose

Create a new subscription plan on a project. Delegates to an Action that enforces resource-sync, the plan policy, and cache invalidation before a plan.created event fires.

The following rules are enforced — identical inputs are rejected by the dashboard too:

name is 5-255 chars and unique per project.
currency_id must be supported by an active payment method on the project.
billing_cycle = lifetime forces billing_cycle_count = 1.
recurring = true is rejected for crypto / platform-currency plans.
newcomers_only, customers_only, churned_only are mutually exclusive.
resources must link to at least one existing project resource — a plan with no resource cannot be redeemed.

Required ability

project-subscription-plan:create

Input schema

{
  "type": "object",
  "required": [
    "project_id",
    "name",
    "currency_id",
    "price",
    "billing_cycle",
    "resources"
  ],
  "properties": {
    "project_id": {
      "type": "string",
      "description": "UUID of the parent project."
    },
    "name": {
      "type": "string",
      "description": "Plan name (min 5, max 255 chars, unique per project)."
    },
    "currency_id": {
      "type": "string",
      "description": "UUID of the currency. Must be supported by an active payment method on the project."
    },
    "price": {
      "type": "number",
      "description": "Plan price as a decimal (min 0)."
    },
    "billing_cycle": {
      "type": "string",
      "description": "One of days, weeks, months, years, lifetime."
    },
    "billing_cycle_count": {
      "type": "integer",
      "description": "How many billing_cycle units per charge (min 1, max 99). Must be 1 when billing_cycle=lifetime."
    },
    "resources": {
      "type": "array",
      "description": "UUIDs of project_resources this plan grants access to. Required — a plan with no linked resource cannot be redeemed."
    },
    "trial_days": {
      "type": "integer",
      "description": "Free trial length in days (0-365)."
    },
    "description": {
      "type": "string",
      "description": "Optional plan description. Max 1000 chars, HTML is filtered."
    },
    "newcomers_only": {
      "type": "boolean",
      "description": "Restrict to users with no prior subscription on this project. Mutually exclusive with customers_only and churned_only."
    },
    "customers_only": {
      "type": "boolean",
      "description": "Restrict to users with at least one prior subscription. Mutually exclusive with newcomers_only and churned_only."
    },
    "churned_only": {
      "type": "boolean",
      "description": "Restrict to users whose last subscription ended. Mutually exclusive with newcomers_only and customers_only."
    },
    "recurring": {
      "type": "boolean",
      "description": "Defaults to true. Must be false for crypto / platform-currency plans."
    },
    "single_use": {
      "type": "boolean",
      "description": "Subscribers can only purchase this plan once."
    },
    "access_codes_only": {
      "type": "boolean",
      "description": "Plan can only be redeemed via access code (no direct checkout)."
    },
    "active": {
      "type": "boolean",
      "description": "Defaults to true. Set false to create in draft state."
    }
  }
}

Output shape

{
  "data": {
    "id": "pln_01HX...",
    "name": "Premium Monthly",
    "project_id": "prj_01HX...",
    "price": "29.00",
    "billing_cycle": "months",
    "active": true
  }
}

Example prompts

"Create a $29/month Premium plan on project prj_01HX... with a 7-day trial, linked to resource rsc_01HY...."

"Add a one-time 'Starter Access' plan priced at $49 with lifetime duration, linked to the Onboarding Pack resource."

Failure modes

VALIDATION_FAILED — missing resources, lifetime-count mismatch, mutual-exclusion violated, or underlying Action policy rejects (name collision, unsupported currency, recurring-vs-crypto conflict).
RESOURCE_NOT_FOUND — project_id doesn't exist in your token's scope.
TOKEN_MISSING_ABILITY — token lacks project-subscription-plan:create.