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
Sandbox delivers only to test recipients. Use 9925:BE0314595348 (SPF Economie, the standard Peppol test receiver) as your to.peppolId. Real companies — including any result from the Peppol Directory — can't receive sandbox documents; sending to them fails after submission.
The sandbox never expires. You can keep using sk_sandbox_* keys alongside production keys for ongoing testing — even after upgrading to a paid plan.
Test via CLI — no SDK install needed:
npm install -g @getpeppr/cli then getpeppr login --key sk_sandbox_... --sandbox, then getpeppr send --to 9925:BE0314595348 --amount 100 --watch. The --to value is the SPF Economie recipient test ID, not a Legal Entity identifier to provision. See the CLI docs.
Sender tax identity differs between sandbox accounts. Read GET /v1/identity before the first send and apply its sandboxFirstSend.line. Two compatible profiles are returned:
  • A routing-only sender receives vatCategory: "O" and vatRate: 0.
  • A sender carrying a tax identifier receives vatCategory: "AE" and vatRate: 0.
The CLI quickstart performs this preflight automatically. Arbitrary VAT-bearing tests still require the appropriate sender tax identity; the invoice from field never changes it.
When something fails — sandbox surfaces the same structured error responses as production. See Error Handling for the full list of HTTP status codes, error shapes, and remediation hints. Each failed send is also logged with its reason in the console dashboard timeline.
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 Identifiers

A Legal Entity and a Peppol Identifier are two separate steps. Creating a Legal Entity creates the company record. Attaching a Peppol Identifier registers the routing identity used by the Peppol network.

FlowSandbox behavior
Standard account onboardinggetpeppr auto-registers a Storecove test routing identifier (de:lwid:10101010-STO1022888-88, where the middle block carries your Legal Entity id) so the account exists on the test network. This lets you send out-of-scope (no-VAT) test invoices immediately (set each line's vatCategory to "O"). To send VAT-bearing invoices you must first register a VAT number on the Peppol identity page — a routing identifier alone carries no tax identity.
Platform Legal Entities APIEach customer Legal Entity is created first, then its requested Peppol Identifier is verified and attached. Fake registry numbers may fail with verification_failed / not_found.
Sandbox does not mean every fake identifier works. The sandbox lets you create test Legal Entities and send test documents, but registry-style verification still expects a supported identifier format and, for supported registry checks, a real or known testable number. The Legal Entity is created first and its identifier reaches the test network only once a registry has confirmed it, so a number your registry rejects is never published. If a number the registry does accept is already held by someone else on the test network, registration then fails with an already_registered result.

Belgian identifiers

For Belgian companies, use 0208 with the 10-digit BCE/KBO enterprise number. Do not include the BE prefix in the identifier value.

Input you may haveUse in getpepprNotes
BE06856602370208:0685660237Belgian VAT number converted to the enterprise-number Peppol scheme.
06856602370208:0685660237Already in the preferred Belgian format.
BE0765432146 (fake)Avoid for verification testsMay create the Legal Entity but fail verification or network registration.
9925 is the VAT-number Peppol scheme. For Belgian customer Legal Entities, getpeppr recommends 0208 because it is the Belgian enterprise-number scheme and matches the current Belgian mandate direction.

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.

LimitSandboxStarterProBusiness
Rate limit / key10 req/min60 req/min120 req/min300 req/min
Validation rate limit / key20 req/min120 req/min240 req/min600 req/min
Rate limit / account50 req/min300 req/min600 req/min1,500 req/min
Team members131025
Webhook endpoints13510
Invoices / monthUnlimited (test)100 included800 included2,000 included
EnvironmentTest networkLive 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.

Fully supported

  • Send invoices and credit notes
  • Retrieve invoice details and status
  • Offline gateway validation for SDK fields, UBL generation, and Peppol business rules
  • 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",
  "validateDocument":   "partial",
  "directoryLookup":    "supported",
  "directorySearch":    "supported",
  "contacts":           "supported",
  "webhooks":           "supported",

  "importInvoice":      "partial",

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

Going to Production

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

  1. Subscribe to a paid plan (Starter, Pro, or Business) from the console.
  2. Complete onboarding — register your Legal Entity and Peppol Identifier. See the Onboarding Setup guide.
  3. Create a production API key (sk_live_*) from the console.
  4. 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