Documents

Overview

The Documents API handles file storage, organization, and PDF generation. Upload certificates of analysis, invoices, spec sheets, shipping labels, and any other business documents. Organize them into folders and share them with customers through the portal.

For recurring document types, create templates with dynamic fields. The generation endpoint merges your data into a template and returns a ready-to-use PDF — no external tools required.

Upload a Document

Upload any file type. Specify a document type for filtering and organization. Files are stored securely and served from the WhaleTools CDN.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Upload a COA
const doc = await whale.documents.create({
  name: 'Batch 2026-03 Certificate of Analysis',
  type: 'coa',
  file: fileBuffer,
  filename: 'coa-batch-2026-03.pdf',
  folder_id: 'fold_compliance',
  metadata: {
    batch_number: '2026-03',
    product_id: 'prod_abc123',
    expiration_date: '2027-03-10'
  }
})

// Response
{
  "id": "doc_550e8400",
  "name": "Batch 2026-03 Certificate of Analysis",
  "type": "coa",
  "filename": "coa-batch-2026-03.pdf",
  "size_bytes": 245780,
  "mime_type": "application/pdf",
  "url": "https://cdn.whaletools.dev/documents/doc_550e8400.pdf",
  "folder_id": "fold_compliance",
  "created_at": "2026-03-10T12:00:00Z"
}

Generate from Template

Generate PDFs by merging data into a template. Templates define the layout — headers, tables, footers, branding — and the data fills in the dynamic fields. Ideal for invoices, COAs, spec sheets, and shipping labels.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Generate an invoice from a template
const invoice = await whale.documents.generate({
  template_id: 'tmpl_invoice_v2',
  data: {
    invoice_number: 'INV-2026-0042',
    customer_name: 'Acme Corp',
    customer_email: 'billing@acme.com',
    line_items: [
      { name: 'Widget Pro', quantity: 50, unit_price: 29.99 },
      { name: 'Widget Mini', quantity: 100, unit_price: 9.99 }
    ],
    subtotal: 2498.50,
    tax: 199.88,
    total: 2698.38,
    due_date: '2026-04-10'
  }
})

// Response
{
  "id": "doc_a1b2c3d4",
  "name": "Invoice INV-2026-0042",
  "type": "invoice",
  "filename": "INV-2026-0042.pdf",
  "url": "https://cdn.whaletools.dev/documents/doc_a1b2c3d4.pdf",
  "template_id": "tmpl_invoice_v2",
  "created_at": "2026-03-10T12:05:00Z"
}

// Generate a COA
const coa = await whale.documents.generate({
  template_id: 'tmpl_coa_standard',
  data: {
    product_name: 'Premium Extract',
    batch_number: 'B2026-0312',
    results: {
      potency: '95.2%',
      heavy_metals: 'Pass',
      microbials: 'Pass',
      residual_solvents: 'Pass'
    },
    lab_name: 'Certified Labs Inc.',
    tested_date: '2026-03-08'
  }
})

Folders & Organization

Organize documents into folders for easy retrieval. Folders can be nested and shared with team members. Assign documents to folders at upload time or move them later.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Create a folder
const folder = await whale.documents.folders.create({
  name: 'Compliance',
  parent_id: null  // top-level folder
})

// Response
{
  "id": "fold_compliance",
  "name": "Compliance",
  "parent_id": null,
  "document_count": 0,
  "created_at": "2026-03-10T12:00:00Z"
}

// Create a subfolder
const subfolder = await whale.documents.folders.create({
  name: 'Q1 2026',
  parent_id: 'fold_compliance'
})

// List documents in a folder
const docs = await whale.documents.list({
  folder_id: 'fold_compliance',
  sort: 'created_at:desc'
})

// Move a document to a folder
await whale.documents.update('doc_550e8400', {
  folder_id: 'fold_compliance'
})

Customer Portal

Share documents with customers through the customer portal. Link documents to orders, products, or customer profiles. Customers can view and download shared documents from their account without contacting support.

const whale = new WhaleClient({ apiKey: 'wk_live_...' })

// Share a COA with a customer
await whale.documents.update('doc_550e8400', {
  shared: true,
  shared_with: {
    customer_id: 'cust_xyz789',
    order_id: 'ord_456def'
  }
})

// Link a document to a product (visible on product page)
await whale.documents.update('doc_550e8400', {
  linked_product_id: 'prod_abc123'
})

// Customers see shared documents at:
// https://portal.whaletools.dev/documents

API Reference

All document management endpoints. Authenticated with your API key. Scoped to your store.