Skip to main content

​
Two sandboxes, two use cases

Shared sandbox

Always available. No setup. Use sk_test_DOCS_SHARED_KEY in any request right now. Best for reading the docs and testing single calls.

Your own sandbox

Isolated tenant, private API key, your own clock. Best for integration testing, CI, or anything where you need clean data.

​
Shared sandbox

The shared sandbox is a real tenant pre-seeded with three plans and a test customer. Every code example in these docs points at it. You can run any curl straight from your terminal without signing up. 
# Try it right now — list the pre-seeded plans
curl https://api.useplinth.com/v1/plans \
  -H "Authorization: Bearer sk_test_DOCS_SHARED_KEY"
What’s pre-seeded:
ResourceDetails
PlansStarter (₦2,000/month), Pro (₦5,000/month), Max (₦12,000/month)
Customercus_docs_001 — customer@docs-sandbox.ng
ClockControllable — advance it to simulate renewals
Limits on the shared sandbox:
  • Clock advances are rate-limited to 1 per minute — prevents one reader from breaking examples for everyone else
  • Write operations (create customers, subscriptions) work but data is shared across all readers
For anything more than single-call testing, use your own sandbox.

​
Your own sandbox

One call gives you an isolated tenant with your own API key, plans, and clock. It expires automatically after 24 hours.
1

Create your sandbox

Call POST /sandbox/create — no API key required, it’s a public endpoint.
curl -X POST https://api.useplinth.com/sandbox/create
Response
{
  "object": "sandbox",
  "tenant_id": "ten_01JXY...",
  "api_key": "sk_test_a1b2c3d4e5f6...",
  "expires_at": "2026-06-19T12:00:00Z",
  "plans": [
    { "id": "pln_01JAA...", "name": "Starter", "amount_minor": "200000", "currency": "NGN", "interval": "month" },
    { "id": "pln_01JAB...", "name": "Pro",     "amount_minor": "500000", "currency": "NGN", "interval": "month" },
    { "id": "pln_01JAC...", "name": "Max",     "amount_minor": "1200000","currency": "NGN", "interval": "month" }
  ],
  "customer": {
    "id": "cus_01JAD...",
    "name": "Sandbox Customer",
    "email": "customer@sandbox.ng"
  }
}
2

Save your API key

Export it as an environment variable so every subsequent call uses it automatically.
export NOMBA_KEY="sk_test_a1b2c3d4e5f6..."
Or click “Use my sandbox key” below to have these docs swap every code block automatically.
3

Run calls against your isolated tenant

# Subscribe your pre-seeded customer to Pro
curl -X POST https://api.useplinth.com/v1/subscriptions \
  -H "Authorization: Bearer $NOMBA_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"customer_id\": \"<your customer id from the response above>\",
    \"plan_id\": \"<your pro plan id>\",
    \"payment_method_id\": \"tok_test_visa\"
  }"
4

Fast-forward time

Your sandbox has its own clock. Advance it to trigger renewals and test dunning without waiting.
# Advance 1 month
curl -X POST https://api.useplinth.com/admin/clock/advance \
  -H "Authorization: Bearer $NOMBA_KEY" \
  -d '{"advanceSeconds": 2592000}'

# Run the billing tick
curl -X POST "https://api.useplinth.com/admin/tick?tenant_id=<your tenant id>" \
  -H "Authorization: Bearer $NOMBA_KEY"

​
Use my sandbox key in these docs

Paste your sandbox API key below. Every code block on this site will show your key instead of sk_test_DOCS_SHARED_KEY. Nothing is sent anywhere — it’s stored only in your browser’s localStorage.
This is a client-side convenience feature. Your key is never transmitted to our servers through this form — only via the API calls you make from your own terminal.

​
Sandbox vs production

Shared sandboxYour sandboxProduction
API key prefixsk_test_sk_test_sk_live_
Real moneyNoNoYes
Real Nomba account neededNoNoYes
Isolated dataNo (shared)YesYes
Clock controlYes (rate-limited)Yes (full)No
ExpiresNever24 hoursNever
Never use a sk_live_ key in code examples or commit it to a repository. Live keys charge real cards.