> ## Documentation Index > Fetch the complete documentation index at: https://altostrat.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Update a subscription > Updates a subscription. This endpoint supports multiple distinct operations. You can change product quantities, add or remove products, update metadata, or perform an action like `pause`, `resume`, or `sync`. Only one type of operation (e.g., `product_quantities`, `add_products`, `action`) is allowed per request. ## OpenAPI ````yaml /api/en/workspaces.yaml patch /workspaces/{workspaceId}/billing-accounts/{billingAccountId}/subscriptions/{subscriptionId} openapi: 3.0.3 info: title: Altostrat Workspaces API version: 1.0.0 description: >- The Altostrat Workspaces API is the microservice responsible for tenancy, billing, user identity, and organizational hierarchy. It serves as the foundational layer for all multi-tenancy and subscription logic within the Altostrat SDX platform, enabling the secure separation of customer data and resources for SD-WAN, network automation, and agentic AI features. This API allows you to programmatically manage: - **Workspaces:** The top-level containers for all tenant resources, users, and billing configurations. - **Organizations:** Hierarchical entities used to model customer tenants or business units, track resource usage, and apply limits. - **Billing & Subscriptions:** The financial accounts and Stripe-powered subscriptions that govern access to Altostrat SDX features and resources. - **Members & Access:** The users and their specific roles (Owner, Admin, Viewer) within a workspace. Developers use this API to build the structural foundation and manage the billing lifecycle upon which all other Altostrat SDX automation and AI features operate. servers: - url: https://v1.api.altostrat.io description: Production API Server security: - bearerAuth: [] tags: - name: Workspaces description: Manage workspaces, the top-level containers for all resources. - name: Workspace Members description: Manage user access and roles within a workspace. - name: Organizations description: Manage hierarchical organizations for tenancy and resource segmentation. - name: Billing Accounts description: Manage financial accounts linked to Stripe for billing and subscriptions. - name: Subscriptions description: Manage product subscriptions powered by Stripe. - name: Invoices description: Retrieve invoice history and preview upcoming billing changes. - name: Payment Methods description: Manage customer payment methods for subscriptions. - name: Public description: Unauthenticated endpoints for retrieving public organization information. paths: /workspaces/{workspaceId}/billing-accounts/{billingAccountId}/subscriptions/{subscriptionId}: patch: tags: - Subscriptions summary: Update a subscription description: >- Updates a subscription. This endpoint supports multiple distinct operations. You can change product quantities, add or remove products, update metadata, or perform an action like `pause`, `resume`, or `sync`. Only one type of operation (e.g., `product_quantities`, `add_products`, `action`) is allowed per request. parameters: - $ref: '#/components/parameters/WorkspaceId' - $ref: '#/components/parameters/BillingAccountId' - $ref: '#/components/parameters/SubscriptionId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSubscriptionRequest' responses: '200': description: The subscription was updated successfully. content: application/json: schema: $ref: '#/components/schemas/Subscription' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': description: >- Unprocessable Entity - The update violates a business rule, such as reducing capacity below current usage. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: type: unprocessable_entity code: insufficient_capacity message: >- This update is invalid as it would leave the workspace under-provisioned for 'users'. Workspace requires 10, but the new total capacity would only be 5. doc_url: https://docs.altostrat.io/errors/insufficient_capacity '500': $ref: '#/components/responses/ServerError' components: parameters: WorkspaceId: name: workspaceId in: path required: true description: The ID of the workspace. schema: type: string example: ws_a1b2c3d4e5f6g7h8 BillingAccountId: name: billingAccountId in: path required: true description: >- The ID of the billing account, which corresponds to a Stripe Customer ID (`cus_...`). schema: type: string example: cus_a1b2c3d4e5f6g7h8 SubscriptionId: name: subscriptionId in: path required: true description: The ID of the Stripe subscription (`sub_...`). schema: type: string example: sub_a1b2c3d4e5f6g7h8 schemas: UpdateSubscriptionRequest: type: object description: >- Specify one of the following operations: `action`, `product_quantities`, `add_products`, or `remove_products`. `metadata` can be combined with `product_quantities`. properties: action: type: string description: Perform a state change action on the subscription. enum: - pause - resume - sync product_quantities: type: object description: >- Replace all current product quantities with this new set. To remove a product, omit it from this object. A `quantity` of 0 is not allowed; omit the key to remove. additionalProperties: type: integer minimum: 1 example: locations: 20 users: 100 add_products: type: object description: >- Add new products to the subscription or increase the quantity of existing ones. additionalProperties: type: integer minimum: 1 example: sso: 1 remove_products: type: array description: A list of product types to remove from the subscription. items: type: string enum: - locations - users - sso example: - sso metadata: type: object description: >- A set of key-value pairs to store with the subscription. Will be merged with existing metadata. example: project_id: proj_def456 Subscription: type: object properties: id: type: string description: >- Unique identifier for the subscription (Stripe Subscription ID), prefixed with `sub_`. example: sub_a1b2c3d4e5f6g7h8 billing_account_id: type: string description: The ID of the billing account this subscription belongs to. example: cus_a1b2c3d4e5f6g7h8 status: type: string description: The status of the subscription. enum: - active - past_due - unpaid - canceled - incomplete - incomplete_expired - trialing - paused example: active currency: type: string description: The three-letter ISO currency code for the subscription. enum: - usd - zar - eur - gbp - aud example: usd product_quantities: type: object description: >- A map of meterable product types to their subscribed quantities and pricing details. additionalProperties: $ref: '#/components/schemas/ProductQuantity' example: locations: price_id: price_123abc quantity: 10 interval: month users: price_id: price_456def quantity: 50 interval: month metadata: type: object description: A set of key-value pairs that you can attach to an object. additionalProperties: type: string example: order_id: '6735' current_period_start: type: string format: date-time nullable: true description: The start of the current billing period. example: '2025-10-15T00:00:00Z' current_period_end: type: string format: date-time nullable: true description: The end of the current billing period. example: '2025-11-15T00:00:00Z' created_at: type: string format: date-time nullable: true description: The timestamp when the subscription was created. example: '2025-10-15T12:30:00Z' updated_at: type: string format: date-time nullable: true description: The timestamp when the subscription was last updated in our system. example: '2025-10-20T09:00:00Z' ErrorResponse: type: object properties: type: type: string description: A broad category for the error (e.g., 'invalid_request_error'). example: invalid_request_error code: type: string description: A short, unique string identifying the specific error. example: parameter_missing message: type: string description: A human-readable description of what went wrong. example: The 'name' parameter is required for this request. doc_url: type: string description: >- A direct link to the documentation page for this specific error code. example: https://docs.altostrat.io/errors/parameter_missing ProductQuantity: type: object properties: price_id: type: string description: The ID of the Stripe Price object. example: price_1Kb... quantity: type: integer description: The number of units subscribed to. example: 50 interval: type: string nullable: true description: The billing interval for this product. enum: - day - week - month - year example: month responses: BadRequest: description: >- Bad Request - The request was malformed or contained invalid parameters. The response body will contain details about the error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: type: invalid_request_error code: parameter_invalid message: The 'name' parameter cannot exceed 50 characters. doc_url: https://docs.altostrat.io/errors/parameter_invalid Unauthorized: description: >- Unauthorized - The request was not authenticated. Ensure you have provided a valid Bearer token in the Authorization header. Forbidden: description: >- Forbidden - The authenticated user does not have permission to perform this action. NotFound: description: Not Found - The requested resource could not be found. ServerError: description: Internal Server Error - An unexpected error occurred on the server. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: type: api_error code: internal_server_error message: An internal server error occurred. Please try again later. doc_url: https://docs.altostrat.io/errors/internal_server_error securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: 'Enter your JWT in the format: Bearer {token}' ````