Multi-Tenancy

Entity Model

Entity model

┌───────────────────────────────────────────┐
│              Your Platform                │
│         (Account-level API key)           │
└───────────────────┬───────────────────────┘
                    │
      ┌─────────────┼─────────────┐
      │             │             │
      ▼             ▼             ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│  Entity A │ │  Entity B │ │  Entity C │
├───────────┤ ├───────────┤ ├───────────┤
│ • Data    │ │ • Data    │ │ • Data    │
│ • Config  │ │ • Config  │ │ • Config  │
│ • Users   │ │ • Users   │ │ • Users   │
└───────────┘ └───────────┘ └───────────┘

Each entity is fully isolated—data never mixes between entities.

Creating Entities

Create an entity for each of your customers:

Create entitytypescript

import SpaceInvoices from "@space-invoices/js-sdk";

const sdk = new SpaceInvoices("YOUR_API_KEY");

const entity = await sdk.entities.create({
  name: "Acme Corporation",
  address: "123 Business Ave",
  city: "San Francisco",
  post_code: "94102",
  country: "United States",
  currency_code: "USD",
});

Per-Entity Operations

All operations are scoped to an entity:

Entity-scoped operationstypescript

// List invoices for a specific entity
const invoices = await sdk.invoices.list({ entity_id: "ent_123" });

// Create customer in a specific entity
const customer = await sdk.customers.create(
  { name: "New Customer", email: "customer@example.com" },
  { entity_id: "ent_123" },
);

Entity Settings

Customize defaults and number formats per entity:

Update settingstypescript

await sdk.entities.update("ent_123", {
  settings: {
    default_invoice_note: "Thank you for your business!",
    default_invoice_payment_terms: "Payment due within 30 days.",
    number_formats: {
      invoice: "INV-{YYYY}-{NUM}",
      estimate: "EST-{YYYY}-{NUM}",
      credit_note: "CN-{YYYY}-{NUM}",
    },
  },
});

Number format placeholders: {NUM} (sequential), {YYYY} (year), {YY} (2-digit year), {MM} (month), {DD} (day).

Listing Entities

List entitiestypescript

// Basic listing
const entities = await sdk.entities.list();

// With pagination
const paginated = await sdk.entities.list({ limit: 20, next_cursor: "ent_abc..." });

// With search
const searched = await sdk.entities.list({ search: "acme" });