Payments API¶

Manage workspace subscriptions and billing through Stripe integration.

Endpoints¶

Get Available Plans¶

GET /api/v1/payment/workspace/{workspaceSlug}/plans

List available subscription plans.

Path Parameters

Parameter	Type	Description
`workspaceSlug`	string	Workspace identifier

Response

[
  {
    "plan": "FREE",
    "name": "Free",
    "description": "Get started with basic features",
    "price": 0,
    "currency": "USD",
    "interval": "month",
    "features": {
      "maxUsers": 3,
      "maxProjects": 1,
      "maxStorageGB": 5
    }
  },
  {
    "plan": "PRO",
    "name": "Pro",
    "description": "For growing teams",
    "price": 29,
    "currency": "USD",
    "interval": "month",
    "features": {
      "maxUsers": 10,
      "maxProjects": 10,
      "maxStorageGB": 50
    }
  },
  {
    "plan": "TEAM",
    "name": "Team",
    "description": "For larger organizations",
    "price": 99,
    "currency": "USD",
    "interval": "month",
    "features": {
      "maxUsers": 50,
      "maxProjects": 50,
      "maxStorageGB": 200
    }
  }
]

Required Permission: WORKSPACE_READ

Get Current Subscription¶

GET /api/v1/payment/workspace/{workspaceSlug}/subscription

Get the workspace's current subscription status.

Response

{
  "plan": "PRO",
  "status": "ACTIVE",
  "currentPeriodStart": "2024-02-01T00:00:00Z",
  "currentPeriodEnd": "2024-03-01T00:00:00Z",
  "cancelAtPeriodEnd": false,
  "canceledAt": null
}

Subscription Status Values

Status	Description
`ACTIVE`	Subscription is active
`PAST_DUE`	Payment failed, grace period
`CANCELED`	Subscription canceled
`INCOMPLETE`	Payment pending

Required Permission: WORKSPACE_READ

Get Workspace Usage¶

GET /api/v1/payment/workspace/{workspaceSlug}/usage

Get current resource usage for the workspace.

Response

{
  "users": {
    "current": 5,
    "limit": 10,
    "percentage": 50
  },
  "projects": {
    "current": 3,
    "limit": 10,
    "percentage": 30
  },
  "storage": {
    "currentBytes": 2147483648,
    "limitBytes": 53687091200,
    "percentage": 4
  }
}

Required Permission: WORKSPACE_READ

Create Checkout Session¶

POST /api/v1/payment/workspace/{workspaceSlug}/checkout

Create a Stripe Checkout session for subscribing to a plan.

Request Body

{
  "plan": "PRO",
  "successUrl": "https://app.usetotis.com/billing/success",
  "cancelUrl": "https://app.usetotis.com/billing/cancel"
}

Field	Type	Required	Description
`plan`	string	Yes	Plan to subscribe to
`successUrl`	string	Yes	Redirect URL on success
`cancelUrl`	string	Yes	Redirect URL on cancel

Response

{
  "sessionId": "cs_test_abc123",
  "url": "https://checkout.stripe.com/pay/cs_test_abc123"
}

Required Permission: WORKSPACE_EDIT + must be workspace owner

Owner Only

Only workspace owners can manage billing and subscriptions.

Error Responses

Status	Error	Description
400	`BAD_REQUEST`	Cannot checkout for FREE or ENTERPRISE plans
403	`FORBIDDEN`	Not workspace owner

Change Subscription Plan¶

POST /api/v1/payment/workspace/{workspaceSlug}/change-plan

Upgrade or downgrade the subscription plan.

Request Body

{
  "plan": "TEAM"
}

Response

Returns the updated subscription object.

Required Permission: WORKSPACE_EDIT + must be workspace owner

Downgrade Restrictions

Downgrading may fail if current usage exceeds the lower plan's limits.

Validate Downgrade¶

GET /api/v1/payment/workspace/{workspaceSlug}/validate-downgrade

Check if downgrade to a specific plan is possible.

Query Parameters

Parameter	Type	Description
`plan`	string	Target plan for downgrade

Response

{
  "canDowngrade": false,
  "blockers": [
    "Current storage usage (15GB) exceeds PRO plan limit (10GB)",
    "Current project count (12) exceeds PRO plan limit (10)"
  ]
}

Required Permission: WORKSPACE_READ

Cancel Subscription¶

POST /api/v1/payment/workspace/{workspaceSlug}/cancel

Cancel the workspace subscription.

Query Parameters

Parameter	Type	Default	Description
`immediately`	boolean	false	Cancel immediately vs. at period end

Response

Returns the updated subscription object.

Required Permission: WORKSPACE_EDIT + must be workspace owner

Period End Cancellation

By default, subscriptions cancel at the end of the billing period, allowing continued access until then.

Create Billing Portal Session¶

POST /api/v1/payment/workspace/{workspaceSlug}/billing-portal

Create a Stripe Billing Portal session for managing payment methods and invoices.

Query Parameters

Parameter	Type	Description
`returnUrl`	string	URL to return to after portal session

Response

{
  "url": "https://billing.stripe.com/session/abc123"
}

Required Permission: WORKSPACE_EDIT + must be workspace owner

Get Stripe Public Key¶

GET /api/v1/payment/public-key

Get the Stripe publishable key for frontend integration.

Response

{
  "publicKey": "pk_live_abc123..."
}

No Authentication Required

This endpoint is public as the publishable key is meant to be used client-side.

Subscription Plans¶

Plan	Users	Projects	Storage	Price
FREE	3	1	5 GB	$0/mo
PRO	10	10	50 GB	$29/mo
TEAM	50	50	200 GB	$99/mo
ENTERPRISE	Unlimited	Unlimited	Custom	Contact us

Webhook Events¶

Totis handles Stripe webhooks automatically at /api/v1/stripe/webhook:

checkout.session.completed - New subscription created
customer.subscription.updated - Plan changes
customer.subscription.deleted - Cancellation completed
invoice.payment_failed - Payment issues

These events update the local database to reflect subscription changes.