Skip to main content

CreateSubscription creates a new subscription for the organization.

POST 
/api/v1/billing/subscription

Initializes a subscription with the specified plan and billing information. Can optionally start a trial period if the plan offers one. This is typically called during organization onboarding or when upgrading from a free tier.

Authorization​

Requires billing:manage permission. Usually limited to organization admins/owners.

Behavior​

  • Creates subscription in 'trialing' status if start_trial=true and plan has trial_days
  • Creates subscription in 'active' status otherwise
  • Sets current_period_start to now, current_period_end based on billing_period
  • Creates initial invoice if not in trial

Validation​

  • billing_email: Required, must be valid email format
  • plan_id: Optional for seat-based model, required for plan-based model

Response​

Returns the created Subscription with generated ID and initial period dates.

Errors​

  • ALREADY_EXISTS: Organization already has an active subscription
  • NOT_FOUND: Specified plan_id does not exist
  • INVALID_ARGUMENT: Validation failed (e.g., invalid email)
  • PERMISSION_DENIED: Caller lacks billing:manage permission

Request​

Responses​

A successful response.