Organizations and Environments

Everything in Alguna belongs to an organization — your company’s account. Customers, products, subscriptions, invoices, API keys and settings are all scoped to it, and nothing is shared with another organization. Inside your organization sit two independent environments, one or more selling entities, your team, and your customers. This page explains that structure, and then how to map your own product’s tenants onto it.

---

​

The organization

The organization is the boundary. Every record carries its organization, every API key is issued against one, and every query is answered within it. If your company has one Alguna account, that is your organization. Inside it: Business details, branding, tax configuration, invoicing rules and automations are all organization-level: set once, applied to everything underneath.

---

​

Environments

Sandbox and production are two complete, independent copies of that structure. A key issued in one is rejected by the other, records do not exist across both, and there is no copy or promote step between them. Switch between them with the environment switcher in the dashboard, or by changing the base URL and key in your integration. Configuration you build in sandbox is not carried across — see Testing and sandbox for how to work with both.

---

​

Selling from more than one entity

If you invoice from several registered businesses — one per country, say — model each as a legal entity and assign each customer to the right one. The legal entity is the From party on the invoice, carries the tax registration, and owns the receivable; tax treatment and revenue schedules follow that assignment. A merchant is a different thing that is easy to confuse with it: display identity only, for invoices you issue on behalf of another business. Your legal entity remains seller of record. Both are covered in Legal entities and merchants.

---

​

Modelling your own tenants

If your product is multi-tenant, the question is usually how your tenants, workspaces or accounts map onto Alguna. The mapping is: Your billable tenant is an Alguna customer. Whatever unit signs up, gets an invoice and can churn — a workspace, an org, a team — is one customer record. From there:

• Keep your own IDs, don’t store Alguna’s. Put your tenant identifier in the customer’s aliases. Every endpoint that takes a customer {id} also accepts an alias, so GET /customers/tenant_abc123 works with no ID mapping table on your side. GET /customers/lookup?alias=… resolves one to the Alguna ID when you do need it.
• Attribute usage by the same identifier. Usage events carry account, which accepts a customer ID or any of its aliases — so your meter emits the tenant ID it already has.
• Nest tenants one level with customer families. A parent customer with child customers gives you a group that can be invoiced together through roll-up billing while usage and revenue stay attributed to the child that incurred them. The relationship is set in the dashboard, not the API.
• Gate features per tenant with entitlements, rather than reading subscription state and inferring access in your own code.

Two things not to do: don’t create an Alguna organization per tenant — organizations are for your company, not your customers, and per-tenant organizations break reporting, catalog reuse and API access. And don’t reuse one customer record for several of your tenants; a customer is the unit of invoicing, so merged tenants cannot be billed or churned separately later.

---

​

Next steps