Skip to content
Space Invoices Documentation

SaaS Platforms

Use Space Invoices for SaaS when invoicing is a product feature, not just a back-office task. The usual model is one entity per customer, with your backend deciding whether customers use your own UI, embedded UI, or direct dashboard access.

Common Underestimation

Teams usually do not struggle with creating the first invoice. They struggle with customer-specific entity setup, access control, branding defaults, and country-specific behavior once many tenants are live.

Who This Is For

  • SaaS teams adding invoicing as a premium or core workflow
  • product teams that need customer isolation, branding, and compliance without building everything from scratch
  • engineering teams that want to start with one customer in sandbox and scale to many tenants later

Best Fit / Not A Fit

Best fit

  • your customers issue invoices under their own business identity
  • each customer needs their own numbering, settings, branding, and compliance rules
  • your backend already owns customer onboarding

Not a fit

  • you only invoice from one central business and do not need tenant isolation
  • you want a zero-integration standalone app instead of product-level embedding
  • you have no backend service that can manage entities or access control

How It Works

SaaS multi-tenant structure
┌───────────────────────────────────────────────┐
│             Your SaaS Platform                │
├───────────────┬───────────────┬───────────────┤
│  Customer A   │  Customer B   │  Customer C   │
│  entity_123   │  entity_456   │  entity_789   │
├───────────────┼───────────────┼───────────────┤
│  Invoices     │  Invoices     │  Invoices     │
│  Customers    │  Customers    │  Customers    │
│  Items        │  Items        │  Items        │
│  Settings     │  Settings     │  Settings     │
└───────────────┴───────────────┴───────────────┘
  • use an account key in your backend to create and manage entities
  • choose JavaScript SDK if you want full workflow control
  • choose Embed SDK if you want the fastest tenant-facing UI
  • choose React UI if you want component ownership inside a React product
  • add User Access Guide when customers need direct dashboard access

Start with one sandbox tenant and your control plane first. Do not design the whole customer UI before you prove the entity model.

Entity Model

The standard SaaS model is:

  • one customer in your product = one entity in Space Invoices
  • your platform user record stays in your system
  • documents, customers, items, templates, and settings live inside that entity

That gives each customer:

  • isolated data
  • their own invoice numbering
  • their own branding
  • country-specific compliance behavior

First Sandbox Milestone

Before you design your full product UX, prove this flow in sandbox:

  1. create one entity for a sample customer
  2. apply branding defaults
  3. issue one invoice under that entity
  4. render the PDF and verify numbering and tax behavior
  5. decide whether end users stay in your UI or get dashboard access

1. Onboard A Customer

When a customer signs up on your platform, create an entity for them:

Onboardtypescript
// title: Onboard customer
const entity = await sdk.entities.create({
  name: customer.companyName,
  address: customer.address,
  city: customer.city,
  country: customer.country,
  currency_code: customer.currency,
});

// Store entity.id with your customer record
await db.customers.update(customer.id, { entityId: entity.id });
Create Entity API →

2. Set Up Branding

Brandingtypescript
// title: Custom branding
await sdk.entities.update(entity.id, {
  settings: {
    pdf_template: {
      logo_url: "https://example.com/logo.png",
      primary_color: "#3B82F6",
    },
    email_defaults: {
      sender_name: customer.companyName,
    },
  },
});
Update Entity API →

3. Issue Documents In Their Context

All operations are scoped to the customer’s entity:

Invoicetypescript
// title: Create invoice for customer
const _invoice = await sdk.invoices.create(
  {
    customer: { name: "End Client", email: "client@example.com" },
    items: [{ name: "Monthly subscription", quantity: 1, price: 99 }],
  },
  { entity_id: customer.entityId },
);
Create Invoice API →

4. Choose How Customers Access Invoicing

Simple approach — Use server-brokered entity API key access when full entity scope is acceptable:

Dashboard simpletypescript
// title: Embedded dashboard (simple)
const token = await sdk.entityUsers.generateToken(entity.id, user.id);

// Redirect to embedded dashboard
window.location.href = `https://app.spaceinvoices.com/embed?token=${token}`;

With roles — Use user-based access for team collaboration:

Dashboard userstypescript
// title: Embedded dashboard (with users)
// Add user to entity
await sdk.entityUsers.add(entity.id, {
  email: user.email,
  role: "admin",
});

// Generate magic link
const token = await sdk.entityUsers.generateToken(entity.id, user.id);
const _dashboardUrl = `https://app.spaceinvoices.com/embed?token=${token}`;

See User Access Guide for detailed comparison.

Common Workflow And Gotchas

  • create the entity at customer signup or activation, not lazily after live documents exist
  • keep your product’s tenant ID in metadata so document traces reconcile cleanly
  • choose account keys for platform operations and entity keys only for isolated tenant-facing flows
  • decide early whether your customers can invite teammates, because that changes your access model
  • keep branding and default settings part of onboarding so invoices do not start with placeholder business data

Compliance Notes

  • each entity’s country determines the default compliance behavior
  • EU customers may need VIES validation and reverse-charge handling
  • fiscalization and e-invoicing depend on country-specific setup, not just invoice creation
  • sandbox is the right place to validate country behavior before enabling live traffic

Why This Model Works

  • Full isolation — Data never mixes between customers
  • Custom branding — Each customer sees their logo and settings
  • Compliance handled — We manage tax rules per customer’s country
  • Usage-based pricing — Bill based on invoices created per entity
  • Optional self-service — Customers can manage their own invoices

Integration Flow

SaaS integration flow
┌──────────────┐     ┌─────────────────┐     ┌──────────────┐
│  Customer    │     │   Your SaaS     │     │    Space     │
│  Signs Up    │────▶│   Platform      │────▶│   Invoices   │
└──────────────┘     └─────────────────┘     └──────────────┘
                            │                       │
                            │  1. Create Entity     │
                            │─────────────────────▶│
                            │                       │
                            │  2. Store entity_id   │
                            │◀─────────────────────│
                            │                       │
                            │  3. Create invoices   │
                            │─────────────────────▶│
                            │                       │

Clear Next Action

If this matches your architecture, prove one tenant flow in sandbox before you design the full product experience.