> ## 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. # Create a billing account > Creates a new billing account within a workspace. This also creates a corresponding Customer object in Stripe. The behavior is constrained by the workspace's billing mode; for `single` mode, only one billing account can be created. For `pooled` and `assigned` modes, up to 10 can be created. ## OpenAPI ````yaml /api/en/workspaces.yaml post /workspaces/{workspaceId}/billing-accounts 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: post: tags: - Billing Accounts summary: Create a billing account description: >- Creates a new billing account within a workspace. This also creates a corresponding Customer object in Stripe. The behavior is constrained by the workspace's billing mode; for `single` mode, only one billing account can be created. For `pooled` and `assigned` modes, up to 10 can be created. parameters: - $ref: '#/components/parameters/WorkspaceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBillingAccountRequest' responses: '201': description: The billing account was created successfully. content: application/json: schema: $ref: '#/components/schemas/BillingAccount' '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 request violates a business rule, such as exceeding the billing account limit for the workspace mode. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: type: unprocessable_entity code: billing_account_limit_exceeded message: >- Only one billing account is allowed when the workspace is in single billing mode. doc_url: >- https://docs.altostrat.io/errors/billing_account_limit_exceeded '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 schemas: CreateBillingAccountRequest: type: object required: - name - email properties: name: type: string description: The name for the new billing account. Maximum 100 characters. example: ACME Corp (EU) email: type: string format: email description: The primary billing email address. Maximum 150 characters. example: billing-eu@acme.com phone: type: string nullable: true description: The billing contact phone number. Maximum 50 characters. example: '+442071234567' description: type: string nullable: true description: >- An optional description for the billing account. Maximum 200 characters. example: For all European operations. currency: type: string description: >- The three-letter ISO currency code. If not provided, it will default based on the workspace or system settings. enum: - usd - zar - eur - gbp - aud example: eur address: $ref: '#/components/schemas/Address' BillingAccount: type: object properties: id: type: string description: >- Unique identifier for the billing account (Stripe Customer ID), prefixed with `cus_`. example: cus_a1b2c3d4e5f6g7h8 workspace_id: type: string description: The ID of the workspace this billing account belongs to. example: ws_a1b2c3d4e5f6g7h8 name: type: string description: The name of the billing account. example: ACME Corp Billing email: type: string format: email description: The primary billing email address. example: billing@acme.com phone: type: string nullable: true description: The billing contact phone number. example: '+15551234567' description: type: string nullable: true description: An optional description for the billing account. example: For US-based operations currency: type: string description: The three-letter ISO currency code for the billing account. enum: - usd - zar - eur - gbp - aud example: usd address: $ref: '#/components/schemas/Address' created_at: type: string format: date-time description: The timestamp when the billing account was created. example: '2025-10-29T00:40:06.000000Z' updated_at: type: string format: date-time description: The timestamp when the billing account was last updated. example: '2025-10-29T00:40:06.000000Z' 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 Address: type: object properties: country: type: string description: Two-letter country code (ISO 3166-1 alpha-2). example: US line1: type: string nullable: true description: Address line 1 (e.g., street, PO Box, or company name). example: 123 Main Street line2: type: string nullable: true description: Address line 2 (e.g., apartment, suite, unit, or building). example: Suite 456 city: type: string nullable: true description: City, district, suburb, town, or village. example: San Francisco state: type: string nullable: true description: State, county, province, or region. example: CA postal_code: type: string nullable: true description: ZIP or postal code. example: '94105' 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}' ````