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.
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.
Sending with VAT in sandbox — your test account ships with a routing identifier but no VAT number. Two cases:
  • No-VAT test invoices send immediately. Set each line's vatCategory to "O" (outside the scope of VAT) — this is what the CLI quickstart above sends. No setup required.
  • VAT-bearing invoices (e.g. vatRate: 21) require a VAT number registered in Settings → Peppol Identity first. Without one, the send is rejected with a 422 "Your sender identity has no VAT number registered" — the sender's tax identity comes from your registered Peppol Identity, never the invoice from field.
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.

Flow Sandbox behavior
Standard account onboarding getpeppr auto-registers a Storecove test routing identifier (de:lwid:10101010-STO-XX) 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 in Settings → Peppol Identity — a routing identifier alone carries no tax identity.
Platform Legal Entities API Each 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. If a fake identifier is already held in Storecove's test network, the Legal Entity can be created while network registration 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 have Use in getpeppr Notes
BE0685660237 0208:0685660237 Belgian VAT number converted to the enterprise-number Peppol scheme.
0685660237 0208:0685660237 Already in the preferred Belgian format.
BE0765432146 (fake) Avoid for verification tests May 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.

Limit Sandbox Starter Pro Business
Rate limit / key 10 req/min 60 req/min 120 req/min 300 req/min
Validation rate limit / key 20 req/min 120 req/min 240 req/min 600 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
  • 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",

  "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:

  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