Documenso Cost Tuning

Key insight: Documenso does not charge per API call or per document on paid plans. Cost optimization is about choosing the right plan tier, not reducing API usage.

Instructions

Step 1: Right-Size Your Plan

Decision tree:
1. Personal use, < 5 docs/month? → Free tier
2. Individual developer, unlimited docs? → Individual ($30/mo)
3. Multiple team members collaborating? → Team plan
4. Need SSO, audit logs, or compliance? → Enterprise
5. Want full control, have DevOps capacity? → Self-host (AGPL, free)

Step 2: Template Reuse to Save Time (Not Money)

Templates don't save money (paid plans are unlimited), but they save developer time and reduce errors:

// WITHOUT templates: rebuild every time (slow, error-prone)
async function createContractManual(client: Documenso, signer: Signer) {
  const doc = await client.documents.createV0({ title: `Contract — ${signer.name}` });
  // Upload PDF, add recipient, add 6 fields... every time
  // 7+ API calls per document
}

// WITH templates: one API call + send
async function createContractFromTemplate(templateId: number, signer: Signer) {
  const res = await fetch(
    `https://app.documenso.com/api/v1/templates/${templateId}/create-document`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.DOCUMENSO_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        title: `Contract — ${signer.name}`,
        recipients: [{ email: signer.email, name: signer.name, role: "SIGNER" }],
      }),
    }
  );
  const doc = await res.json();
  // One call to create, one to send = 2 API calls
  await fetch(`https://app.documenso.com/api/v1/documents/${doc.documentId}/send`, {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.DOCUMENSO_API_KEY}` },
  });
  return doc;
}

Step 3: Self-Hosted Cost Analysis

Self-hosted (AGPL license, free for commercial use):
  Server: ~$20/mo (small VPS with Docker)
  Database: Included (PostgreSQL in Docker)
  Email: ~$5/mo (Mailgun, Resend, etc.)
  SSL: Free (Let's Encrypt)
  Total: ~$25/mo for unlimited everything

vs. Cloud Team plan: $30/mo+

Self-host makes sense when:
  - You need data sovereignty (documents never leave your infra)
  - You want zero vendor lock-in
  - You have DevOps capacity to maintain it
  - You need custom branding / white-labeling

Step 4: Monitor Usage Patterns

// Track document creation patterns for capacity planning
async function getUsageStats(client: Documenso) {
  const { documents } = await client.documents.findV0({
    page: 1,
    perPage: 100,
    orderByColumn: "createdAt",
    orderByDirection: "desc",
  });

  const now = new Date();
  const thisMonth = documents.filter(
    (d: any) => new Date(d.createdAt).getMonth() === now.getMonth()
  );

  const byStatus = thisMonth.reduce((acc: Record<string, number>, d: any) => {
    acc[d.status] = (acc[d.status] || 0) + 1;
    return acc;
  }, {});

  console.log(`This month: ${thisMonth.length} documents`);
  console.log(`By status:`, byStatus);
  console.log(`Completion rate: ${((byStatus.COMPLETED || 0) / thisMonth.length * 100).toFixed(0)}%`);
}

Step 5: Reduce Waste

Cost waste patterns (time-based, not money-based on unlimited plans):
1. Abandoned drafts → Set up cleanup script to delete old DRAFT documents
2. Duplicate documents → Use templates instead of manual creation
3. Failed sends → Validate recipient emails before creating documents
4. Test data in production → Use staging environment for development

Error Handling

Resources

• Documenso Pricing
• Self-Hosting Guide
• Template Best Practices
• Fair Use Policy

Next Steps

For architecture patterns, see documenso-reference-architecture.