📖 Looking for karrio's legacy docs? Visit docs.karrio.io

Document Generation & Templates

Community Edition
Core Feature

Karrio’s document generation system provides template-based document creation for GS1 labels, invoices, and custom business documents. This system is designed for flexible document generation using customizable templates with dynamic data binding.

Core Features

Template Management

Create, update, and manage document templates with full version control and preview capabilities.

Document Generation

Generate documents using templates with dynamic data injection and multiple output formats.

GS1 Label Support

Specialized support for GS1 barcode labels with compliant formatting and encoding.

ℹ

Shipping Labels

Shipping labels are automatically generated when creating shipments and don’t require the document generation API. They support PDF, PNG, and ZPL formats.

API Reference

Document Generation

Generate documents using templates with the document generation API.

Generate Document

1curl -X POST "https://api.karrio.io/v1/documents/generate" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "template_id": "gs1-label-template",
6    "doc_format": "PDF",
7    "doc_name": "product_label.pdf",
8    "data": {
9      "product_name": "Sample Product",
10      "gtin": "1234567890123",
11      "batch_number": "LOT001",
12      "expiry_date": "2025-12-31"
13    },
14    "options": {
15      "page_size": "A4",
16      "orientation": "portrait"
17    }
18  }'

Response:

1{
2  "template_id": "gs1-label-template",
3  "doc_format": "PDF",
4  "doc_name": "product_label.pdf",
5  "doc_file": "JVBERi0xLjQKJeLjz9MKMSAwIG9iagp..."
6}

Generate with Inline Template

1curl -X POST "https://api.karrio.io/v1/documents/generate" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "template": "<html><body><h1>{{title}}</h1><p>{{content}}</p></body></html>",
6    "doc_format": "PDF",
7    "doc_name": "custom_document.pdf",
8    "data": {
9      "title": "Invoice #001",
10      "content": "Thank you for your business"
11    }
12  }'

Template Management

Manage document templates for reuse across multiple document generation requests.

List Templates

1curl -X GET "https://api.karrio.io/v1/documents/templates" \
2  -H "Authorization: Token YOUR_API_KEY"

Response:

1{
2  "count": 3,
3  "results": [
4    {
5      "id": "tpl_1234567890",
6      "name": "GS1 Product Label",
7      "slug": "gs1-product-label",
8      "description": "Standard GS1 barcode label template",
9      "related_object": "other",
10      "active": true,
11      "object_type": "document-template",
12      "preview_url": "https://api.karrio.io/v1/documents/templates/tpl_1234567890/preview",
13      "metadata": {
14        "category": "labels",
15        "version": "1.0"
16      }
17    }
18  ]
19}

Create Template

1curl -X POST "https://api.karrio.io/v1/documents/templates" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Custom Invoice Template",
6    "slug": "custom-invoice",
7    "description": "Corporate invoice template with branding",
8    "template": "<html><head><style>body{font-family: Arial}</style></head><body><h1>{{company_name}}</h1><div>Invoice: {{invoice_number}}</div><div>Date: {{invoice_date}}</div><table><tr><th>Item</th><th>Quantity</th><th>Price</th></tr>{{#items}}<tr><td>{{name}}</td><td>{{quantity}}</td><td>{{price}}</td></tr>{{/items}}</table></body></html>",
9    "related_object": "other",
10    "metadata": {
11      "category": "invoices",
12      "version": "1.0"
13    }
14  }'

Response:

1{
2  "id": "tpl_1234567891",
3  "name": "Custom Invoice Template",
4  "slug": "custom-invoice",
5  "description": "Corporate invoice template with branding",
6  "template": "<html>...</html>",
7  "active": true,
8  "related_object": "other",
9  "object_type": "document-template",
10  "preview_url": "https://api.karrio.io/v1/documents/templates/tpl_1234567891/preview",
11  "metadata": {
12    "category": "invoices",
13    "version": "1.0"
14  }
15}

Get Template

1curl -X GET "https://api.karrio.io/v1/documents/templates/tpl_1234567890" \
2  -H "Authorization: Token YOUR_API_KEY"

Update Template

1curl -X PATCH "https://api.karrio.io/v1/documents/templates/tpl_1234567890" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "description": "Updated GS1 barcode label template",
6    "metadata": {
7      "category": "labels",
8      "version": "1.1"
9    }
10  }'

Delete Template

1curl -X DELETE "https://api.karrio.io/v1/documents/templates/tpl_1234567890" \
2  -H "Authorization: Token YOUR_API_KEY"

Template System

Template Engine

Karrio uses a powerful template engine that supports:

  • Variable Substitution: {{variable_name}}
  • Conditional Logic: {{#condition}}...{{/condition}}
  • Loops: {{#items}}...{{/items}}
  • HTML/CSS: Full HTML and CSS support for styling

Template Types

Related Objects

Templates can be associated with different object types:

  • shipment: Templates for shipment-related documents
  • order: Templates for order-related documents
  • other: General-purpose templates

Data Binding

Templates receive data through the data parameter in generation requests:

1{
2  "data": {
3    "company_name": "ACME Corp",
4    "invoice_number": "INV-2024-001",
5    "items": [
6      {"name": "Product A", "quantity": 2, "price": 25.00},
7      {"name": "Product B", "quantity": 1, "price": 50.00}
8    ]
9  }
10}

Format Support

PDF Output

Professional PDF documents with:

  • Vector graphics support
  • Print-ready formatting
  • Searchable text
  • Embedded fonts

Other Formats

The system supports various output formats specified via the doc_format parameter.

Common Use Cases

GS1 Labels

Generate compliant GS1 barcode labels for product identification:

1curl -X POST "https://api.karrio.io/v1/documents/generate" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "template_id": "gs1-label",
6    "doc_format": "PDF",
7    "data": {
8      "gtin": "1234567890123",
9      "product_name": "Sample Product",
10      "batch_number": "LOT001",
11      "expiry_date": "2025-12-31",
12      "serial_number": "SN001"
13    }
14  }'

Custom Invoices

Create branded invoice documents:

1curl -X POST "https://api.karrio.io/v1/documents/generate" \
2  -H "Authorization: Token YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "template_id": "company-invoice",
6    "doc_format": "PDF",
7    "data": {
8      "company": {
9        "name": "ACME Corporation",
10        "address": "123 Business St",
11        "phone": "(555) 123-4567"
12      },
13      "invoice": {
14        "number": "INV-2024-001",
15        "date": "2024-01-15",
16        "due_date": "2024-02-15"
17      },
18      "customer": {
19        "name": "John Doe",
20        "address": "456 Customer Ave"
21      },
22      "items": [
23        {
24          "description": "Product A",
25          "quantity": 2,
26          "unit_price": 25.00,
27          "total": 50.00
28        }
29      ],
30      "totals": {
31        "subtotal": 50.00,
32        "tax": 4.00,
33        "total": 54.00
34      }
35    }
36  }'

Business Documents

Generate various business documents using templates:

  • Packing Lists: Detailed item lists for shipments
  • Certificates: Custom certificates and compliance documents
  • Reports: Formatted business reports
  • Letters: Branded business correspondence

Best Practices

Template Design

  • Use semantic HTML structure for better rendering
  • Include CSS for professional styling
  • Test templates with sample data before production use
  • Use meaningful variable names for clarity

Data Management

  • Validate data before sending to generation API
  • Use consistent data structures across templates
  • Include error handling for missing variables
  • Consider data security for sensitive information

Performance

  • Cache frequently used templates
  • Use template IDs instead of inline templates for better performance
  • Optimize template complexity for faster rendering
  • Consider batch processing for multiple documents

Getting Started

  1. Create your first template using the template management API
  2. Test document generation with sample data
  3. Integrate with your application using the generation API
  4. Monitor usage and optimize templates as needed

Next Steps

Need help with document generation? Join our community Discord or check our template examples.