Concepts

ShipPDF generates finished PDFs from reusable templates. This page defines the core terms and how they connect, and ends with a glossary for quick reference.

Workspaces and projects

Everything you make lives in a workspace, your team’s account and the boundary for billing, members, and API tokens. Inside a workspace, templates are grouped into projects so related work stays together, such as one project per client or per kind of document.

Templates

A template is the reusable design at the heart of ShipPDF. It holds the layout (what the page looks like) and a data schema (the fields it expects to be filled in). You design a template once, then generate many PDFs from it. The layout stays fixed while the data changes with every PDF.

Drafts, problems, and publishing

While you are editing it, a template is a draft. ShipPDF checks a draft for problems, like a missing field or a broken layout, that would stop it from producing a clean PDF. When the draft is ready, you publish it, which freezes it as an immutable revision (shown as a version, v1, v2, and so on). Only published revisions can generate PDFs, so what you ship is always complete. Editing again starts a new draft on top of the last published revision.

Documents and credits

A document is one generated PDF. You generate a document from a published template plus the data for this particular output, and each one spends a credit from your workspace balance.

Generation is asynchronous. A new document starts as queued, moves to processing, and ends at completed or failed. A completed document carries a short-lived pdf_url to download the file, and a failed one does not spend a credit.

Retries are safe with an idempotency key, a value you attach to a request so that repeating it counts as the same request rather than a new one. Reuse the key on a retry and ShipPDF replays the original document instead of spending another credit.

Data binding

The link between a template and a document is data binding. The JSON you send is matched against the template’s data schema, and each field drops into its place in the layout. The schema is the contract, so once you know a template’s schema you know exactly what data to send to fill it.

Ways to generate

Once a template is published, you can generate documents three ways, all producing the same result:

• A form inside ShipPDF, for a quick one-off without writing code.
• The REST API, for your own software to generate at scale. See the Quickstart and API reference.
• An AI assistant over MCP, where you ask in plain language and the assistant calls ShipPDF to do the work. See the MCP reference.

Tokens, scopes, and MCP

Programmatic access uses a workspace API token, a secret in the form sk_live_.... Each token carries scopes, which decide what it can do, such as reading templates or generating documents. A token only ever has the access you grant it.

MCP, the Model Context Protocol, is the open standard that lets an AI assistant connect to an outside tool. ShipPDF exposes an MCP endpoint, so an assistant like Claude or ChatGPT can discover your templates and generate PDFs through ShipPDF, using the same tokens and scopes as the API.

Glossary