Documentation Index
Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
Use this file to discover all available pages before exploring further.
WorkspaceSubscription is the billing anchor for a Well workspace. It stores the Stripe customer identity and the active Stripe pricing-plan subscription reference alongside a mirrored subscription status that is kept in sync by the Stripe webhook pipeline. Each workspace owns exactly one subscription row, created during the workspace-creation flow and updated automatically as Stripe events arrive. It is the record the billing middleware consults to gate premium features and the record the Stripe webhook handler writes to when a subscription transitions state.
| Naming | Value |
|---|
| Object | WorkspaceSubscription |
Resource type (JSON:API type) | workspace_subscription |
| Collection / records root | — (not a records root) |
| REST base | /v1/workspace-subscriptions |
| Entity class | WorkspaceSubscription |
Internal object. Not currently exposed on the public REST API. The operations below describe the intended contract.
API operations
| Operation | Method & path | Status |
|---|
| List | GET /v1/workspace-subscriptions | 🟡 Planned |
| Retrieve | GET /v1/workspace-subscriptions/{id} | 🟡 Planned |
| Create | POST /v1/workspace-subscriptions | 🟡 Planned |
| Update | PATCH /v1/workspace-subscriptions/{id} | 🟡 Planned |
| Delete | DELETE /v1/workspace-subscriptions/{id} | 🟡 Planned |
Data model
Attributes
| Field | Type | Required | Constraints | Allowed values | Description |
|---|
| workspace_subscription_id | string (UUID) | ✅ Yes | unique, gen_random_uuid() default, never null | any UUID | The public-facing stable identifier for this subscription record. Exposed on the JSON:API envelope as the resource id. |
| status | string | null | ⚪ No | nullable; value is mirrored from Stripe pricing-plan subscription servicing_status | ”active” | “canceled” | “paused” | Mirrors the Stripe pricing-plan subscription’s servicing_status. Set by the Stripe webhook handler (customer.subscription.updated / checkout.session.completed) and by the subscription sync service. NULL until the first Stripe event is processed. |
| stripe_customer_id | string | null | ⚪ No | nullable | Stripe customer ID string (prefix cus_) | The Stripe Customer object ID for this workspace’s billing account. Written by SubscriptionsService when the workspace is linked to Stripe. |
| stripe_pricing_plan_subscription_id | string | null | ⚪ No | nullable | Stripe Subscription object ID string (prefix sub_) | The Stripe Subscription object ID for the active pricing-plan subscription. Written when the workspace subscribes to a plan and updated on plan changes. |
| created_at | 🔒 system — datetime | ✅ Yes | set by onCreate hook, never null | — | Timestamp when the subscription row was first created. |
| updated_at | 🔒 system — datetime | null | ⚪ No | set by onCreate and onUpdate hooks | — | Timestamp of the most recent mutation to this row. Updated on every Stripe webhook write. |
| deleted_at | datetime | null | ⚪ No | nullable; soft-delete sentinel | — | When set, the subscription row is treated as deleted. Soft-delete is the only removal mechanism; hard deletes do not occur. |
Relationships
| Name | Type | Required | Description |
|---|
| workspace | to-one (ManyToOne) | Yes — the @ManyToOne decorator is declared without nullable:true on this entity | The workspace this subscription record belongs to. A subscription row is always bound to exactly one workspace; the workspace is the tenant boundary for all billing checks. Target entity: Workspace. |
System-computed
- workspace_subscription_id — generated by gen_random_uuid() at the database level on INSERT; also seeded client-side via randomUUID() as the ORM default
- created_at — set by MikroORM onCreate lifecycle hook to new Date(); never user-supplied
- updated_at — set by MikroORM onCreate and onUpdate lifecycle hooks; reflects every Stripe-webhook-driven mutation
- deleted_at — not set by any automated pipeline today; available as the soft-delete sentinel column following the platform convention
- status — written exclusively by the Stripe webhook handler (stripe-webhooks.service.ts) and by SubscriptionsService.syncSubscriptionFromStripe; mirrors Stripe pricing-plan servicing_status (active / canceled / paused)
- stripe_customer_id — written by SubscriptionsService when creating or linking a Stripe Customer for the workspace
- stripe_pricing_plan_subscription_id — written by SubscriptionsService when a pricing-plan subscription is activated or changed
Example
{
"data": {
"type": "workspace_subscription",
"id": "3f8c1a2d-9e4b-47f0-b35a-dc12ef890abc",
"attributes": {
"workspace_subscription_id": "3f8c1a2d-9e4b-47f0-b35a-dc12ef890abc",
"status": "active",
"stripe_customer_id": "cus_QxR3mN7pLwT9bZ",
"stripe_pricing_plan_subscription_id": "sub_1Pf7KkLmN9oQ2rS4tU6vW8",
"created_at": "2024-11-14T09:32:11.000Z",
"updated_at": "2025-03-01T16:47:05.000Z",
"deleted_at": null
},
"relationships": {
"workspace": {
"data": { "type": "workspace", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
}
}
}
}
apps/api/src/database/entities/WorkspaceSubscription.ts · domain: workspace · tier: Platform
