Sandbox

A free, permanent testing environment with full SDK access. Understand what you can do — and what's different from production.

What is the Sandbox?

The sandbox is a free, permanent testing environment. Invoices are sent to the Peppol test network — no real documents are transmitted, and no charges apply.

What you get

Unlimited test invoices — send as many as you need
Full SDK access — core invoice sending, validation, contacts, and webhooks all work the same as in production
Validation API — client-side and server-side validation
Contacts & Directory — manage contacts and search the Peppol Directory
Webhooks — receive real-time status updates for test documents

The sandbox never expires. You can keep using sk_sandbox_* keys alongside production keys for ongoing testing — even after upgrading to a paid plan.

import { Peppol } from "@getpeppr/sdk";

// Sandbox (default) — no real invoices sent
const sandbox = new Peppol({
  apiKey: "sk_sandbox_...",
});

// Production — live Peppol network
const live = new Peppol({
  apiKey: "sk_live_...",
  environment: "production",
});

// Advanced options
const custom = new Peppol({
  apiKey: "sk_live_...",
  environment: "production",
  timeout: 60_000,       // 60s (default: 30s)
  baseUrl: "https://...", // custom endpoint
});

Sandbox Limits

The sandbox has lower rate limits and quotas than paid plans. These limits are designed for development and testing — not for production workloads.

Limit	Sandbox	Starter	Pro	Business
Rate limit / key	10 req/min	60 req/min	120 req/min	300 req/min
Rate limit / account	50 req/min	300 req/min	600 req/min	1,500 req/min
Team members	1	3	10	25
Webhook endpoints	1	3	5	10
Invoices / month	Unlimited (test)	100 included	800 included	2,000 included
Environment	Test network	Live Peppol network + sandbox for testing

Rate limits apply per API key and per account. The per-account limit is the total across all your keys. If you hit a 429, the SDK retries automatically with exponential backoff.

Unsupported Operations

Some operations are not available due to how the Peppol network and our provider (Storecove) work. These limitations apply to all plans, not just the sandbox.

Not supported

Draft invoices — documents are submitted immediately to the Peppol network. There is no draft state.
Update / delete — invoices are immutable after submission. To correct an invoice, send a credit note.
Import — importing external invoices is not currently available.

Fully supported

Send invoices and credit notes
Retrieve invoice details and status
Peppol Directory search and lookup
Contacts and bank accounts management
Webhook delivery notifications

Call GET /v1/capabilities to programmatically check which operations are available, with detailed status and notes for each.

GET /v1/capabilities (simplified)

{
  "sendInvoice":        "supported",
  "sendCreditNote":     "supported",
  "getInvoice":         "supported",
  "listInvoices":       "partial",
  "directoryLookup":    "supported",
  "directorySearch":    "supported",
  "contacts":           "supported",
  "webhooks":           "supported",

  "createDraftInvoice": "not_supported",
  "deleteInvoice":      "not_supported",
  "updateInvoice":      "not_supported",
  "importInvoice":      "not_supported"
}

Going to Production

When you're ready to send real invoices over the Peppol network, you'll need to:

Subscribe to a paid plan (Starter, Pro, or Business) from the console.
Complete onboarding — register your Legal Entity and Peppol Identifier. See the Onboarding Setup guide.
Create a production API key (sk_live_*) from the console.
Switch your SDK configuration to use the production key.

Production invoices are legally binding documents delivered over the live Peppol network. Make sure your Legal Entity details are correct before sending.

You can use sandbox and production keys side by side. Run your test suite against sk_sandbox_* while your application uses sk_live_* in production.

Authentication

Send an Invoice