Skip to content
Space Invoices Documentation

Marketplaces

Use this path when your marketplace has many sellers, each of whom must issue documents under their own business identity. The core design rule is simple: one seller should normally map to one entity.

Common Underestimation

Teams often underestimate how expensive seller isolation becomes after launch. The first invoice is easy. The hard part is keeping seller-specific numbering, branding, corrections, exports, and reporting clean without mixing data.

Who This Is For

  • marketplaces with many independent sellers or vendors
  • platforms that need seller isolation, seller branding, and seller-specific numbering
  • engineering teams that need unified reporting without shared seller data

Best Fit / Not A Fit

Best fit

  • each seller is a separate legal or operational invoicing party
  • invoices should show seller branding and seller business details
  • your marketplace backend already manages seller onboarding and transactions

Not a fit

  • the marketplace operator is the sole issuer for every order
  • sellers are not distinct invoicing parties
  • you do not need seller-level isolation
  • use an account key in your platform backend to manage seller entities
  • use the JavaScript SDK or API for seller onboarding and invoice issuance
  • add User Access Guide only if sellers or seller staff need dashboard access

Keep reporting and aggregation in your marketplace layer. Do not weaken seller isolation just to make the first integration feel simpler.

Entity Model

Recommended model:

  • one seller = one entity
  • buyer-facing transactions stay in your marketplace domain model
  • invoices are created in the seller’s entity context

This gives each seller their own:

  • numbering
  • branding
  • compliance setup
  • document history

First Sandbox Milestone

Validate the basic seller flow in sandbox:

  1. create one entity for a test seller
  2. map one marketplace transaction to that seller
  3. issue one invoice in the seller’s entity
  4. verify seller branding and numbering
  5. confirm reporting and metadata links back to the marketplace transaction

How It Works

Marketplace multi-seller structure
┌───────────────────────────────────────────────┐
│              Your Marketplace                 │
├───────────────┬───────────────┬───────────────┤
│   Seller A    │   Seller B    │   Seller C    │
│  entity_123   │  entity_456   │  entity_789   │
├───────────────┼───────────────┼───────────────┤
│  Invoices     │  Invoices     │  Invoices     │
│  Customers    │  Customers    │  Customers    │
│  Branding     │  Branding     │  Branding     │
│  Tax Settings │  Tax Settings │  Tax Settings │
└───────────────┴───────────────┴───────────────┘

1. Onboard a Seller

Seller entitytypescript
// title: Create entity for seller
const entity = await sdk.entities.create({
  name: seller.businessName,
  address: seller.address,
  city: seller.city,
  zip: seller.zip,
  country: seller.country,
  taxNumber: seller.taxNumber,
  taxSubject: true,
});

// Store entity ID with seller record
await db.sellers.update(seller.id, { entityId: entity.id });
Create Entity API →

2. Seller Invoices Buyer

When a transaction completes:

Seller invoicetypescript
// title: Create invoice on behalf of seller
const _invoice = await sdk.invoices.create(
  {
    customer: {
      name: buyer.name,
      email: buyer.email,
      address: buyer.shippingAddress,
    },
    items: order.items.map((item) => ({
      name: item.name,
      quantity: item.quantity,
      price: item.price,
    })),
  },
  { entity_id: seller.entityId },
);
Create Invoice API →

3. Give Sellers Dashboard Access (Optional)

Simple approach — Use server-brokered entity API key access when sellers only need full access to their own entity:

Dashboard simpletypescript
// title: Embedded dashboard for seller (simple)
const token = await sdk.entityUsers.generateToken(seller.entityId, seller.userId);

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

With team access — Use user-based access if sellers have staff:

Dashboard userstypescript
// title: Embedded dashboard for seller (with users)
// Add seller as admin of their entity
await sdk.entityUsers.add(seller.entityId, {
  email: seller.email,
  role: "admin",
});

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

See User Access Guide for detailed comparison.

Common Workflow And Gotchas

  • never create seller invoices in a shared entity unless the marketplace operator is the legal issuer
  • keep seller IDs and marketplace order IDs in metadata
  • decide whether invoices are issued at order creation, payment, or fulfillment
  • plan seller support and staff access separately from seller API access
  • test aggregation queries and exports early so finance operations can report across many seller entities

Compliance Notes

  • the seller’s entity country determines most compliance behavior
  • buyer location can still affect tax handling, especially in cross-border sales
  • EU sellers may require VIES validation and reverse-charge behavior
  • sandbox is the safest place to validate per-seller compliance and branding before live rollout

Why This Model Works

  • Seller isolation — Each seller has their own compliant invoicing
  • Proper tax handling — Based on seller’s country and buyer’s location
  • Transaction linking — Connect invoices to marketplace transactions
  • Seller branding — Invoices show seller’s business details
  • Optional self-service — Sellers can manage their own invoices

Integration Flow

Marketplace invoicing flow
┌──────────────┐     ┌─────────────────┐     ┌──────────────┐
│   Buyer      │     │   Marketplace   │     │    Space     │
│   Purchase   │────▶│   Platform      │────▶│   Invoices   │
└──────────────┘     └─────────────────┘     └──────────────┘
                            │                       │
                            │  1. Order placed      │
                            │─────────────────────▶│
                            │                       │
                            │  2. Create invoice    │
                            │     (seller entity)   │
                            │─────────────────────▶│
                            │                       │
                            │  3. Send to buyer     │
                            │─────────────────────▶│
                            │                       │

Clear Next Action

Start with one seller in sandbox, map one transaction to that seller’s entity, and verify the invoice is issued under the right business identity.