Generate a PDF from an existing template

Use this workflow when your workspace already has a published template. Your assistant supplies the data, and ShipPDF generates the PDF using that template’s published revision.

Before you start

Connect your client with documents:create and documents:read. Add templates:read so the assistant can discover templates and inspect their data schemas. If you supply a known template ID and already know its schema, the two document scopes are sufficient.

The template must be published, and the workspace needs available generation credits. If you need to create a template first, follow Author a template with AI.

Ask your assistant

Use ShipPDF to generate invoice INV-1042 for Acme from my published invoice template. Inspect its data schema first and ask me for any missing values. Generate one document, wait for it to complete, and give me the PDF link.

Supply the actual invoice data alongside your request. If you have several invoice templates, include a template ID or project name so the assistant can choose the right one.

1. Find the template and inspect its schema

The assistant calls list_templates, optionally scoped by project_id, then calls get_template_metadata with the selected template_id.

Metadata includes the published revision and data_schema, without the full layout or sample data. Use it to build the generation payload. Field paths and value types must match the template; a description such as “invoice for Acme” is not enough to supply every field.

2. Generate the document

The assistant calls generate_document with the template ID and data. This illustrative payload assumes the chosen template has an invoice.number field; replace it with data matching your template:

{
  "template_id": "tmpl_example",
  "data": {
    "invoice": {
      "number": "INV-1042"
    }
  },
  "idempotency_key": "invoice-INV-1042"
}

A successful call spends one generation credit and returns a document_ref and an initial status such as queued. It does not return a finished PDF immediately.

Use a stable, nonempty idempotency_key for the same intended generation. Retrying with that key returns the original document without charging again. Use a new key for a new document; reusing a key does not regenerate the PDF with changed data.

3. Wait for the PDF

Call get_document using the returned reference:

{
  "document_ref": "doc_example"
}

Poll with a delay between calls until the status is completed or failed. On completion, return pdf_url. On failure, read failure.code and failure.message and explain what needs to be corrected before generating again.

The PDF URL is a short-lived signed link. Download the file while the link is valid. If it expires, call get_document again to request a fresh link. A completed document whose pdf_url is temporarily unavailable can also be read again without starting another generation.

Keep generation separate from template edits

Generating a document supplies runtime data to a published template. It does not edit or publish the template. If the layout needs a change, follow the authoring workflow, publish the corrected revision, and generate a new document.

See Limits and errors for retries, credit errors, and unavailable templates.