Environments

A SimplyFill account has three environments out of the box: development, staging, and production. They're not separate accounts — they're separate publish channels inside the one account, each with its own API keys, its own set of template versions, and its own quota counters.

Environments exist so you can change a PDF without changing what your production callers see. The W-4 you've shipped today keeps generating against version 7 in production while you upload version 8 to development, test it, promote it to staging for a release-candidate run, and finally cut over to production when you're ready.

How environments work

Every API key is scoped to exactly one environment. The key carries that scope as a server-side property — there's no ?env=prod query parameter to forget. The key's environment determines:

1. Which template version a request resolves to. If template T has version 7 published to production and version 8 published only to development, a request with a dev API key resolves to v8; a request with a prod key resolves to v7.
2. Which quota counter the request charges against. Each environment has its own monthly PDF and rate-limit counters. Dev runs don't burn through prod's monthly cap.
3. Which webhooks fire. Webhook configurations are also environment-scoped — see Webhooks.

API key allocation per tier

The API-key count limits from Quotas apply across all environments combined:

On the FREE tier you get one key — it defaults to the development environment so you can experiment without accidentally publishing. PRO and above can split their five (or twenty) keys across dev, staging, and prod however they like. A common allocation: one dev key per engineer, one shared staging key, two prod keys (one for the main app, one for a worker).

The promotion flow

A promotion moves a template version from one environment to the next. Promotions are explicit — there is no "auto-publish on upload." The end-to-end flow:

1. Upload to dev. Re-uploading the source PDF (or using the templates API) creates a new version. The new version is published only to development.
2. Test in dev. Generate a few PDFs with a dev key. Inspect the output. Adjust mappings if needed.
3. Promote to staging. Run POST /api/v1/templates/{id}/promote with { "from": "development", "to": "staging", "version": 8 }. The version is now resolvable by staging keys.
4. Run a release-candidate batch. Generate the bulk of last week's traffic against staging. Compare to production output. Promote forward only if they match.
5. Promote to production. Same endpoint, with "to": "production". The cutover is atomic — the next request with a prod key resolves to the new version.
6. Rollback if necessary. Promotions are reversible. POST /api/v1/templates/{id}/rollback re-publishes the previous version to the named environment. Rollbacks are also atomic.

The full step-by-step is in Multi-environment promotion.

Common patterns

Feature-flagging a template version per environment

You're rolling out a new layout that adds an "employer EIN" field to the offer letter. You don't want the new field on production yet because the upstream HR system isn't sending it. Solution: keep v7 published to production and v8 published to development and staging. Your front-end can call GET /api/v1/templates/{id} to discover which fields the resolved version expects and adapt the form accordingly — same code path in every environment.

Sharing API keys with contractors

Need to give an outside vendor temporary access? Create a fresh dev-environment key, share it, rotate it when they're done. The contractor can experiment without touching your production counters or your published template versions.

Per-environment overage handling

Quota exhaustion behaves the same way in every environment, but the practical impact differs. A FREE-tier dev environment that hits 100% returns 402 Payment Required and blocks further generations — frustrating mid-debug, but harmless. A production environment that hits 100% on FREE means real customers can't generate documents. Most teams budget for production headroom by upgrading at 60–70% rather than at the 80%/95% warning emails (see Quotas).

CI / CD wiring

In your build pipeline, set SIMPLYFILL_API_KEY per stage:

# Dev CI run
SIMPLYFILL_API_KEY=$SIMPLYFILL_DEV_KEY ./scripts/generate-test-pdfs.sh

# Staging release-candidate
SIMPLYFILL_API_KEY=$SIMPLYFILL_STAGING_KEY ./scripts/regression-pdfs.sh

# Production deploy gate
SIMPLYFILL_API_KEY=$SIMPLYFILL_PROD_KEY ./scripts/smoke-pdf.sh

No environment switching, no flag-flipping. The key decides where each batch lands.

What's next

• Templates — versioning, the substrate environments operate over
• Quotas — per-environment rate limits and monthly caps
• Multi-environment promotion — full guided walkthrough