Skip to content

Sandbox Environment

Every 3PI partner starts in sandbox mode — a fully functional environment where you can build and test your integration without consuming credits or affecting production data.

How sandbox mode works

Aspect Sandbox Production
API endpoints Same URLs and behavior Same URLs and behavior
Capability execution Full AI execution Full AI execution
Credit consumption Zero credits Credits charged per request
Usage tracking Tracked separately Tracked for billing
Rate limits Applied normally Applied normally
Daily credit limits Not enforced Enforced
Response format Identical Identical

Sandbox mode is a flag on the partner, not a separate environment. Your API keys, endpoints, and response formats remain identical — the only difference is that credit charges are waived and usage is tagged as sandbox in reporting.

Checking sandbox status

Check whether a partner is in sandbox mode:

curl https://api.vell.ai/api/v1/3pi-partners/42 \
  -H "Authorization: Bearer $VELLOCITY_API_KEY"

{
  "data": {
    "id": 42,
    "organization": "Acme Marketplace",
    "sandbox_mode": true
  }
}

Toggling sandbox mode

Switch between sandbox and production:

curl -X POST https://api.vell.ai/api/v1/3pi-partners/42/toggle-sandbox \
  -H "Authorization: Bearer $ADMIN_API_KEY"

{
  "data": {
    "id": 42,
    "sandbox_mode": false
  },
  "message": "Sandbox mode disabled — partner is now in production."
}

Toggle again to re-enable sandbox mode:

{
  "data": {
    "id": 42,
    "sandbox_mode": true
  },
  "message": "Sandbox mode enabled."
}

Toggle safely

You can switch between sandbox and production at any time. There's no data loss or key invalidation when toggling. Active API keys continue to work in either mode.

What to test in sandbox

Use sandbox mode to validate your full integration before going live:

1. Authentication flow

  • Verify API key authentication works
  • Test capability scoping (ensure restricted capabilities return 403)
  • Confirm IP allowlisting behaves correctly

2. Capability calls

  • Call each capability your integration uses
  • Verify response formats match your parser expectations
  • Test error handling for invalid inputs

3. Rate limiting

  • Simulate burst traffic to test your retry logic
  • Verify 429 responses include proper Retry-After headers
  • Confirm your backoff strategy works

4. Usage tracking

  • Verify the usage endpoint returns expected metrics
  • Confirm sandbox requests are tracked (with zero credits)
  • Test daily/monthly aggregation queries

5. Key lifecycle

  • Create, rotate, and revoke keys
  • Verify revoked keys return 401
  • Test key expiration behavior

Sandbox vs. production usage reports

Usage summaries separate sandbox and production data by default. The /usage endpoint only returns production metrics:

# This returns production-only metrics
GET /3pi-partners/42/usage?period=daily

Sandbox requests are tracked internally but excluded from billing summaries. This means:

  • You can test heavily in sandbox without inflating your usage reports
  • Production metrics are clean and billing-accurate from day one
  • Sandbox usage is still available for debugging via the Vellocity dashboard

Going live checklist

Before toggling to production, verify:

  • All capability calls return expected responses
  • Error handling works for 401, 403, 404, 422, and 429 status codes
  • API key rotation works without downtime
  • Rate limit retry logic is implemented
  • Daily credit limits are set appropriately
  • Usage monitoring is in place
  • Webhook endpoints (if used) are receiving and processing events
  • IP allowlists are configured for production servers