Marketplaces

Each seller gets their own entity, creating invoices for their buyers.

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

Copy

// 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

Copy

// 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 entity API keys:

Dashboard simpletypescript

Copy

// 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

Copy

// 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.

Key Benefits

• 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

Compliance Considerations

• Seller’s entity country determines tax obligations
• EU sellers get automatic VIES validation for B2B
• Cross-border transactions handled automatically

Integration Flow

Marketplace invoicing flow

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

Next Steps

• User Access Guide — Give sellers dashboard access
• Multi-Tenancy Guide — Entity management
• Compliance — Tax handling details