---
title: "Set Workspace Plan From Billing"
method: PUT
path: "/internal/workspaces/{workspace_id}/plan"
tags: ["internal-billing"]
---

# Set Workspace Plan From Billing

`PUT /internal/workspaces/{workspace_id}/plan`

## Request

- Base URL: `https://memory.kagura-ai.com` (the document declares no server; this is the origin it was published from)
- URL: `https://memory.kagura-ai.com/internal/workspaces/{workspace_id}/plan`
- Auth: none declared

Set a workspace's entitlement (plan tier + addon quota) from billing.

Idempotent, service-authenticated, internal-only. Sets ``plan_name``; when
``addons`` is provided it is applied as a FULL REPLACE (dimensions omitted
from the map reset to 0) so a tier change cannot strand a prior tier's addon
bonus; omit ``addons`` to leave them unchanged. Does not perform destructive
downgrade cascades (see module docstring). Returns the full applied addon state.

## Path parameters

- `workspace_id` string, required

## Headers

- `authorization` string, nullable

## Request body

- BillingPlanPush: Entitlement push from the billing service (#954 boundary contract).
  - `plan_name` string, required: Entitlement tier: one of the registered plan keys (free | basic | pro | promax)
  - `status` string, nullable: Billing subscription status (Stripe-agnostic free-form). Billing-owned; accepted for audit/forward-compat, NOT persisted or enforced here.
  - `current_period_end` string, date-time, nullable: Subscription period end. Billing-owned; accepted for audit, not persisted here.
  - `addons` object, nullable: Absolute addon bonus values keyed by addon dimension (memory, mcp_quota, rest_quota, public_quota, member, context, analysis, storage_mb, sleep_contexts, connector). FULL REPLACE: when provided this is the complete addon state — dimensions omitted from the map are reset to 0 (an empty object zeros all). Omit the field entirely (null) to leave existing addons unchanged (tier-only change).

## Response `200`

Successful Response

- BillingPlanPushResult: Echo of the applied entitlement (idempotent).
  - `workspace_id` unknown, required
  - `plan_name` unknown, required
  - `addons` unknown, required
  - `entitlement_source` unknown, required
  - `status` unknown
  - `current_period_end` unknown
  - `applied` unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud.md) · [All operations](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/llms.txt) · [OpenAPI document](https://skmtc.dev/kagura-ai/apis/kagura-memory-cloud/revisions/09f17f5ada29?raw)