Plans and limits

QR Code Agency uses tiered plans. Each API key is bound to one plan, inherited from the workspace owning the key.

Comparison

info: Live mode billing Stripe is in live mode. Every checkout charges real money. There are no test cards. Use the Free plan to evaluate; upgrade when you are ready to ship.

Quotas explained

• The monthly quota counter resets on the 1st of every month at 00:00 UTC.
• Every successful 200 response counts as one. Errors do not count: 400, 401, 403, 404, 422, 429 are free.
• Cache hits count. You got a deliverable, you spent quota.
• Bulk renders count one per item. A bulk of 50 = 50 quota credits.
• Check your remaining quota any time with GET /api/v1/usage/.

note: Going over quota On Starter, Pro, and Agency, overage is allowed and billed per render at the rate above. Stripe creates the invoice line at month close.

On Free and Enterprise, exceeding the quota returns 429 Too Many Requests. Upgrade or wait for the 1st of next month.

Size cap explained

size_inches controls the print dimensions. Combined with dpi, it sets the pixel size:

Asking above your plan cap returns 403 Forbidden with a clear message naming the plan you would need.

DPI cap explained

DPI = dots per inch. Print shops typically want 300 minimum; high-end output (offset press, textile sublimation) prefers 600. Browser-only display can drop to 150 or lower to save bandwidth.

Custom logo gate

The Free plan cannot supply logo_file or logo_url. Logos are the single most expensive operation in the render pipeline (decode, resize, luminance alpha pass, alpha composite) and the most common abuse vector through logo_url (SSRF probes). We reserve them for paid keys.

Dynamic QR allowance

Free includes one active dynamic QR with one lifetime destination edit. The intent is to let you experience the print-once, edit-forever pattern without removing the differentiator that justifies paying.

Once you used your one edit, future PATCH requests on that QR return 402 Payment Required until you upgrade or buy a credit pack.

Paid plans get unlimited edits per QR plus large active-QR allowances (10 on Starter, 200 on Pro, 1 000 on Agency).

Bulk cap

POST /api/v1/generate/bulk/ accepts up to plan.max_bulk_items per request. Free is locked out (returns 403); Starter is 50, Pro is 1 000, Agency and Enterprise are 5 000.

The output is a single ZIP archive plus a manifest.json describing every item. See the Bulk concept page and the bulk endpoint reference.

Choosing a plan

flowchart TD
 A[Start here] --> B{How many<br/>QRs / month?}
 B -->|< 5| C[Free]
 B -->|5 to 500| D{Need custom<br/>logo or 8 in?}
 B -->|500 to 5 000| E{Need 15 in,<br/>600 DPI, or A/B?}
 B -->|5 000 to 25 000| F{Need team<br/>seats or<br/>custom domain?}
 B -->|25 000+| G[Enterprise]
 D -->|Yes| H[Starter]
 D -->|No| C
 E -->|Yes| I[Pro]
 E -->|No| H
 F -->|Yes| J[Agency]
 F -->|No| I

Upgrading and downgrading

Subscriptions are managed via Stripe Customer Portal. From the dashboard go to Billing -> Manage subscription.

Changes are applied as follows:

• Upgrade: prorated, takes effect immediately. Quota and feature gates update on the next request.
• Downgrade: takes effect at end of the current billing period. We keep the higher quota until the period closes.

The Stripe webhook at POST /api/billing/webhook/ syncs every plan change automatically.

Credits as an alternative to subscription

Buy credit packs with POST /api/billing/credits/checkout/. Credits never expire and are consumed before subscription quota:

One credit equals one render. Useful for occasional integration tests or for top-ups between billing cycles.

Reading your current plan and limits

curl https://api.qrstudio.agency/api/v1/usage/ \
 -H "X-Api-Key: smk_..."

{
 "key_prefix": "smk_aBc1",
 "plan": "starter",
 "monthly_quota": 500,
 "used_this_month": 12,
 "remaining": 488,
 "max_size_inches": 8,
 "max_dpi": 300,
 "allow_custom_logo": true,
 "max_active_dynamic_qrs": 10,
 "max_bulk_items": 50
}

Or check it for the entire workspace via the JWT-authed GET /api/v1/usage/me/, which aggregates across every key.