Usage and billing

What counts as a document

• One successful PDF generated with a live key or with the dashboard's Generate PDF button is one document, whatever its page count (up to 50 pages per PDF).
• A request that fails (a validation error, a template error, a render that fails or times out) is not counted.
• Test-key documents and previews are never counted.
• A request replayed with the same Idempotency-Key returns the first document and is not counted again.

GET /v1/account/usage shows the current numbers; so does the dashboard.

Plans

Prices and annual billing are on the pricing page.

Templates per team: Free 5, Starter 25, Growth 100, Pro 2,000 and Scale 2,000. The pricing page shows Pro and Scale as "Unlimited": that is a fair-use limit of 2,000 active templates, set high so that no normal use reaches it. Creating one more gets 402 plan_limit_reached. A deleted template is erased with its versions 30 days after it was deleted. Until then it does not count toward that number, but all templates together, deleted ones included, are limited to that number plus 100. Each template keeps its latest 50 versions and the pinned one. Template changes are limited to 60 a minute per team.

PDFs rendering at the same time per team: Free 1, Starter 2, Growth 3, Pro 4 and Scale 4. Live keys, test keys, previews and the dashboard share this number. A request over it gets 429 rate_limited with details.reason set to concurrency and a Retry-After of 1 second.

The plan called Scale on the pricing page is business in the API (plan in GET /v1/account/usage).

The "Made with CastPDF" footer on the Free plan

Live PDFs of a team on the Free plan (made with a live key or the dashboard's Generate PDF button) carry a small footer on every page: "Made with CastPDF · castpdf.com" in grey 7 pt text, centred about 3 mm above the bottom edge of the page, with a link to castpdf.com. It sits inside the page's bottom margin (20mm unless you set your own). With a very small bottom margin, content that reaches the bottom edge can sit under it.

• Paid plans never get the footer. It goes away from the next PDF once you subscribe.
• Test-key PDFs and previews get the "CASTPDF TEST" watermark instead, never the footer.
• The plan in force when the PDF is made decides: if a subscription ends or a payment stays unpaid past the grace period and the team moves to Free, new live PDFs carry the footer. PDFs made earlier are not changed.

Monthly periods

Usage is counted per monthly period. period_start and period_end in GET /v1/account/usage give the current one, in UTC. On annual plans, the documents are still included per month: the allowance resets every monthly period.

Rollover

On paid plans, the part of a period's own included documents that you did not use carries over into the next period:

• Rollover is used first in the next period, and expires at the end of it: it never carries over twice.
• It is capped at the next period's plan quota (at most one extra month's worth of documents).
• The Free plan has no rollover, and moving to the Free plan ends it.

For example, on a plan with 2,500 documents a month, using 2,100 in one period leaves 400 for the next, which then includes 2,900. The usage endpoint shows them as rollover_docs and includes them in docs_included.

Overage and the spending cap

When a paid plan's included documents (rollover included) are used up, rendering continues as overage, at the plan's price per 1,000 documents (see the table above). Overage is charged per document: the cost is the number of overage documents times the rate, rounded up to the next cent. It is billed after the period ends; an amount under $1 is not billed.

Every paid plan has a spending cap on the overage cost of a period. It starts at twice the plan's monthly price, and you can change it in the dashboard's billing page (up to $10,000). A request whose overage would go over the cap is refused with spending_cap_reached; raising the cap or upgrading lets renders continue at once.

Overage is not available on the Free plan, while a cancellation or a pause is scheduled, while a payment is overdue, without an active subscription, when your subscription is billed in a currency we have no overage rates for yet, while an overage payment is unpaid, or once a period's overage has already been billed early. overage_blocked_reason in the usage endpoint says which applies (free, cancel_scheduled, past_due, no_subscription, currency_unsupported, overage_unpaid or billed_this_period).

Overage is charged in the currency your subscription is billed in. The spending cap is set in US dollars: it counts overage documents at the US dollar rate, whatever currency you pay in.

We email the team's owners and admins at 80% and 100% of the included documents, when overage starts, and when the spending cap is reached.

If an overage payment is declined, we try again every 3 days, up to 3 more times. While it is unpaid, overage is paused: new documents above your plan's included amount are refused until the payment goes through. Update your payment method in the customer portal (the dashboard's billing page links to it): we then try the payment again at once, and overage comes back on as soon as it is paid. If all attempts fail, the payment stays unpaid and overage stays paused for 60 days, unless you update your payment method (we then try again) or write to us. A charged back overage payment pauses overage until we have sorted it out with you.

At the limit

Test keys and previews keep working in every case. Both errors explain the reason in their message.

Idempotency

Networks fail. To retry POST /v1/pdf without risking a second document (and a second charge), send an Idempotency-Key header with a value that identifies the document in your system, such as invoice-INV-042:

curl https://api.castpdf.com/v1/pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-INV-042" \
  -d '{"template_id": "8d1f2c3b-4a5e-4f60-9b7a-1c2d3e4f5a6b", "data": {"number": "INV-042"}, "response": "url"}'

• The key is 1 to 255 printable ASCII characters without spaces, and it is scoped to your workspace.
• A repeated request with the same key and the same body returns the stored document of the first request, without rendering or counting again. The body is compared after sorting its keys, and without response, so a retry may ask for binary instead of url (or the other way round) and still get the same document.
• The same key with a different body, or from the other key mode (test or live), is refused with 422 idempotency_mismatch.
• While the first request is still running, a repeat gets 409 idempotency_conflict. Retry after a moment.
• If the first request failed, the key is released: a retry renders again.
• A replay needs the stored PDF. Once its retention has ended, the replay gets 410 file_expired.
• A key is remembered for at least 24 hours, then forgotten: use a new key for each new document rather than reusing old ones.
• A replay reports no blocked resources (x-blocked-resources: 0), even if the first response did.

Test keys store a document for 1 day when a request has an Idempotency-Key, so replays work in development too.

File retention and signed URLs

Stored PDFs are kept for the plan's file retention (see the table above); documents made with a test key for 1 day. A PDF is stored when:

• the key is live, or
• the request asks for "response": "url", or
• the request has an Idempotency-Key.

A stored PDF has a signed download link: the url in the responses of POST /v1/pdf (with "response": "url"), GET /v1/pdf/:id and GET /v1/documents. The link is signed with HMAC-SHA256, needs no API key, and works until the document's expires_at. After that the file is deleted, the link returns 410 file_expired, and url becomes null. Fetch a new link from GET /v1/pdf/:id whenever you need one; every link of a document expires at the same time.

Stored PDF limits

Each team can keep a limited amount of stored PDFs at a time: Free 500 MB, Starter 5 GB, Growth 20 GB, Pro 60 GB and Scale 200 GB. Test-key PDFs count toward that and have their own limit of 200 MB on every plan. Files leave the count when their retention ends.

• A request that needs a stored file ("response": "url", an Idempotency-Key, or the dashboard's Generate PDF) over the limit gets 429 storage_limit_reached. It is not counted as a document.
• A live-key request for the PDF itself ("response": "binary", no Idempotency-Key) still gets its PDF. It is not stored, so it has no download link.
• If the server is low on disk space, storing PDFs pauses for everyone: requests that need a stored file get 503 service_busy, and PDFs returned directly keep working.

Document records (without the file) stay in the log for 120 days. The metadata you send is deleted after 30 days.