Document Retention and Automatic Deletion (TTL)

Every generated document is stored on PDFMonkey’s servers until it expires or you delete it. You control how long documents live by setting a TTL (Time To Live) on each template. When a document’s TTL expires, PDFMonkey automatically deletes it along with its generated file.

How TTL works

TTL is a per-template setting expressed in seconds. When a document finishes generating successfully, PDFMonkey calculates its expiration time by adding the TTL to the generation timestamp. A background job runs every minute, deleting all documents whose expiration has passed.

The countdown starts when the document reaches the success status, not when it is created or queued.

Configuring TTL in the dashboard

Open a template’s Settings tab and locate the Deletion dropdown. Select the retention period that fits your needs:

The available options depend on your plan. If you select a value your plan does not support, PDFMonkey caps it to your plan’s maximum.

Available TTL values by plan

Setting TTL via the API

When creating or updating a template through the Templates API, include the ttl field with a value in seconds:

{
  "document_template": {
    "identifier": "invoice-template",
    "ttl": 3600
  }
}

The same plan-based capping applies: if you request a TTL that exceeds your plan’s maximum, the API silently uses the highest allowed value instead of returning an error.

What gets deleted

When a document is deleted (whether by TTL expiration, manual deletion in the dashboard, or an API call), PDFMonkey removes:

• The generated file (PDF, PNG, WebP, or JPG) from storage
• The payload (the dynamic data you sent to generate the document)
• The meta data associated with the document

The document no longer appears in API responses or the dashboard. Any share link pointing to the document returns a 404 error.

Plan changes and retention

When you change plans, PDFMonkey adjusts TTL settings to match the new plan’s limits:

• Upgrading: Templates keep their current TTL. If you previously set a lower TTL because of plan restrictions, you can now increase it up to your new plan’s maximum.
• Downgrading: Any template with a TTL exceeding the new plan’s maximum is automatically capped. Existing documents from those templates have their expiration dates recalculated, which may cause documents to expire sooner than originally expected.

See Changing My Plan for a broader overview of how plan changes affect your account.

Manual deletion

If you prefer to delete documents on your own schedule rather than relying on TTL, you have two options:

1. Dashboard: Open the document and click the delete button.
2. API: Send a DELETE request to /api/v1/documents/:id. See the API reference for details.

Manual deletion removes the same data as automatic TTL deletion.

Frequently asked questions

Why was my document deleted before the TTL I set?

If you recently downgraded your plan, PDFMonkey may have recalculated expiration dates for existing documents. A template set to “1 week” on a Pro plan that is downgraded to Starter (1-day maximum) sees its documents’ TTL shortened accordingly.

Can I set different TTL values for different templates?

Yes. TTL is a per-template setting. Each template in your account can have its own retention period, within your plan’s limits.

Does TTL apply to failed documents?

No. Only documents with a success status receive an expiration date. Failed documents are not automatically deleted by the TTL system.

Is there an API to check when a document expires?

The document object does not expose the expires_at field directly. However, you can calculate it from the template’s ttl value and the document’s updated_at timestamp.

Related pages

• Document Statuses and Lifecycle – understand when documents become eligible for auto-deletion
• The Download URL – save files to your own storage before they expire
• Permanent Share Links – how deletion affects share links
• Our Plans – plan-based retention limits at a glance
• Changing My Plan – what happens to TTL settings when you switch plans
• Data Storage and Retention – broader overview of what PDFMonkey stores
• API: Templates – set TTL when creating or updating a template
• API: Documents – delete documents programmatically

Frequently asked questions

How long does PDFMonkey keep my generated documents?

It depends on your plan and TTL setting. Free and Starter plans retain documents for up to 1 day. Pro allows up to 7 days. Pro+ and Premium offer unlimited retention. Within those limits, you set the exact TTL per template.

What data is deleted when a document expires?

When a document is deleted (manually or via TTL), PDFMonkey removes the generated file from storage and clears the payload and meta data. The document no longer appears in the API or dashboard.

Can I delete documents manually instead of using TTL?

Yes. You can delete documents from the PDFMonkey dashboard or by calling the DELETE /api/v1/documents/:id endpoint. Manual deletion removes the same data as automatic TTL deletion.

What happens to my TTL settings if I downgrade my plan?

When you downgrade, any template with a TTL exceeding your new plan's maximum is automatically capped to that maximum. Existing documents from those templates have their expiration dates recalculated accordingly.