WorkspaceSubscription

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" }
      }
    }
  }
}

_{Source: apps/api/src/database/entities/WorkspaceSubscription.ts · domain: workspace · tier: Platform}

Main objects

Supporting objects

Platform objects

Activity objects

Infrastructure objects

API operations

Data model

Attributes

Relationships

System-computed

Example

​API operations

​Data model

​Attributes

​Relationships

​System-computed

​Example

API operations

Data model

Attributes

Relationships

System-computed

Example