PDF Generation API

Introduction

Welcome to the PDF Generation API! This service allows you to dynamically create professional PDF invoices from JSON data. It offers a range of customization options, including language settings, currency formatting, company logos, QR codes, and precise invoice total rounding, making it adaptable to diverse business needs.

Endpoint & Method

Endpoint URL: https://api.json2invoice.com

Method: POST

Authentication

The API secures requests using an API Key. This key must be included in the HTTP headers of your request:

If the API Key is missing, invalid, or not authorized for the operation, the API will respond with a 403 Forbidden error. Your API key is also linked to a customerId on our backend for service usage and billing, which is managed by our API authorization layer.

Request Body Structure

All requests to the API must send a JSON object as the request body. This JSON object has two primary top-level keys:

• data (Required): An object containing all the invoice definitions, content, and customization settings. This is the core of your invoice request. See Core Payload: The `data` Object for details.
• lang (Optional): An object allowing you to override specific translation strings for the current request. See Feature: Translations & Text for details.

Content-Type Header: Ensure your request includes the header Content-Type: application/json.

Example Top-Level Structure:

{
  "data": {
    "language": "en",
    "timezone": "America/New_York",
    "from": { /* Sender Address Object */ },
    "to": { /* Recipient Address Object */ },
    "invoice": { /* Invoice Details Object */ }
    // ... other fields as described in "Core data Object Fields"
  },
  "lang": { // Optional: For overriding specific text elements
    "due_date": "Payment Due By",
    "item_type": "Service Category"
  }
}

Core Payload: The data Object

The data object is where you define the specifics of your invoice. The following fields are available directly within the data object:

Address Object (from, to)

The Address Object is used to specify sender (data.from) and recipient (data.to) details. The JSON key for the sender's address must be from.

Example:

{
  "name": "Example Corp LLC",
  "street": "789 Business Park Ave",
  "place": "Chicago, IL 60601",
  "country": "United States",
  "extra": "Floor 12, Attn: Finance Dept.",
  "address_lines_order": ["name", "extra", "street", "place", "country"]
}

Properties:

Invoice Object (invoice)

The data.invoice object contains the core financial and descriptive details of the invoice itself.

Example Snippet:

{
  "id": "INV-US-2024-101",
  "currency": "USD",
  "taxes_method": "excluded",
  "date": "July 20, 2024",
  "due_date_timestamp": 1724025600,
  "date_format": "MMMM d, yy",
  "subject": "Annual Maintenance Contract",
  "items": [ /* Array of Item Objects */ ],
  "taxes": [ /* Array of Tax Objects */ ],
  "rounding_target_cents": 0,
  "rounding_method": "closest"
}

Properties:

Item Object (invoice.items)

Represents a single line item on the invoice, found within the invoice.items array.

Example:

{
  "item_type": "Service",
  "description": "Graphic Design Services - Logo Package",
  "quantity": "1",
  "unit_price": "750.00",
  "taxes": [1] 
}

If invoice.taxes defines one tax (e.g., Sales Tax at index 0), "taxes": [1] means this item is subject to that Sales Tax. If invoice.taxes was [ "name": "GST", "value": "5", "name": "PST", "value": "7"], then "taxes": [1, 0] would apply GST but not PST to this item.

Properties:

Tax Object (within invoice.taxes)

Defines a specific tax type that can be applied to invoice items. These are listed in the invoice.taxes array. A maximum of 3 tax types can be defined per invoice.

Example:

{
  "name": "State Sales Tax",
  "value": "7.5" 
}

In this example, "value": "7.5" represents a 7.5% tax rate.

Properties:

Feature: Invoice Total Rounding

The API allows for precise rounding of the final invoice total to meet specific monetary conventions (e.g., Swiss rounding to the nearest 0.05 CHF, or rounding to whole currency units). This is controlled by two optional fields within the invoice object: rounding_target_cents and rounding_method.

rounding_target_cents

This field specifies the increment to which the final total should be rounded. It accepts one of the following literal integer values:

• 0: Rounds the total to the nearest whole currency unit (e.g., $10.07 becomes $10.00).
• 5: Rounds the total to the nearest 0.05 of a currency unit (e.g., $10.07 becomes $10.05, $10.08 becomes $10.10).
• 10: Rounds the total to the nearest 0.10 of a currency unit.
• 20: Rounds the total to the nearest 0.20 of a currency unit.
• 50: Rounds the total to the nearest 0.50 of a currency unit.

If rounding_target_cents is not provided, no rounding is applied to the final total beyond standard two-decimal precision for most currencies.

rounding_method

This field defines how the rounding is performed if rounding_target_cents is specified. It accepts one of the following string literals:

• "closest": Rounds to the nearest target increment (standard rounding, half-up).
• "discount" (Default if rounding_target_cents is set but rounding_method is omitted): Always rounds the total down to the nearest target increment (floor).
• "penalty": Always rounds the total up to the nearest target increment (ceiling).

Rounding Adjustment on Invoice

If the rounding calculation results in a difference between the unrounded total and the rounded total, a line item typically labeled "Rounding Adjustment" (or its translation) will automatically appear in the invoice summary, showing the amount of the adjustment (e.g., "-$0.02" or "+$0.03"). The "Amount to be Paid" will reflect the final rounded total.

Example Scenario:

If an invoice's calculated total is $123.47 and you specify:

{
  // ... other invoice fields
  "rounding_target_cents": 5,
  "rounding_method": "closest"
}

The final amount to be paid will be $123.45, and a "Rounding Adjustment: -$0.02" line will be shown.

If the method was "penalty", the total would be $123.50 with an adjustment of "+$0.03".

If the method was "discount", the total would be $123.45 with an adjustment of "-$0.02".

Feature: Dates & Timestamps

The API offers flexibility in specifying and formatting dates for the invoice issue date and due date.

Date Precedence:

For both invoice date and due date, the API uses the following precedence:

1. Pre-formatted String (date / due_date): If you provide a string directly in invoice.date or invoice.due_date, this string will be used as-is on the PDF. This gives you full control over the date's appearance.
2. Unix Timestamp (date_timestamp / due_date_timestamp): If a pre-formatted string is not provided, but a Unix timestamp (seconds since epoch) is given in invoice.date_timestamp or invoice.due_date_timestamp, the API will format this timestamp.
   • The formatting uses the pattern specified in invoice.date_format (default: "d MMMM y").
   • The formatting is localized using the resolved Babel locale (derived from data.babel_locale, data.language, or defaults).
   • The timestamp is interpreted as UTC and then converted to the timezone specified in data.timezone (default: "UTC") before formatting.
3. Automatic Date (for Invoice Date only): If neither invoice.date nor invoice.date_timestamp is provided for the invoice issue date, the API will automatically use the current server date and time (UTC), formatted according to invoice.date_format, data.babel_locale, and data.timezone. The due date is never automatically generated; it will be omitted if not specified.

Date Formatting (invoice.date_format):

The invoice.date_format field accepts date format patterns supported by the Babel library (e.g., "MMMM d, yyyy", "dd.MM.yy", "y-MM-dd").

Timezones (data.timezone):

Use standard IANA timezone identifiers (e.g., "America/New_York", "Europe/Paris", "Asia/Tokyo"). If an invalid timezone is provided, UTC will be used with a warning.

Feature: Numeric & Currency

The API is designed to handle various numeric inputs for quantities and monetary values robustly.

Understanding FlexibleDecimal

Several monetary and quantity fields (like unit_price, discount_amount, quantity, tax.value) in the API are of type FlexibleDecimal. This custom type offers robust parsing for various numeric inputs:

• Standard Numbers: Direct JavaScript numbers (e.g., 150, 125.75) are accepted.
• Numeric Strings: The API intelligently parses strings representing numbers, accommodating common formats:
  • "1234.50" (dot as decimal separator)
  • "1,234.50" (comma as thousands separator, dot as decimal - common in the US)
  • "1.234,50" (dot as thousands separator, comma as decimal - common in parts of Europe)
  • "1'200.00" (apostrophe as thousands separator)
  • "1 200.50" (space as thousands separator)
• An empty string ("") or null for these fields is generally interpreted as 0.00 by the backend due to the custom validation logic.

Currency Formatting

• Babel Locale (data.babel_locale): If provided (e.g., "en_US", "de_DE"), this locale is prioritized for formatting currency amounts according to standard conventions for that locale and the specified invoice.currency.
• Fallback Formatting (data.decimal_separator, data.thousands_separator): If data.babel_locale is not provided or is problematic, the API uses these custom separators along with the invoice.currency code for basic currency formatting. The number of decimal places is determined by standard currency precision (e.g., 2 for USD/EUR, 0 for JPY).

Integer-based Currency (data.use_int_for_currency)

If data.use_int_for_currency is set to true, all monetary FlexibleDecimal fields (e.g., unit_price, total, discount_amount in the invoice object and its sub-objects) must be provided as integers. These integers represent the value in the smallest currency unit (e.g., cents for USD, pence for GBP). For example, $123.45 would be sent as 12345. Quantities are not affected by this setting.

Feature: Logos & Branding

You can include a company logo on your invoices using one of the following methods:

• Image/SVG URL (data.logo_link): Provide a publicly accessible URL to an image file (PNG, JPG recommended) or an SVG file.
  • The API will fetch this image. For SVGs, it attempts to extract the viewBox attribute to help with scaling.
  • Dimensions can be constrained using data.logo_max_height, data.logo_max_width, and influenced by data.logo_min_height. The aspect ratio is maintained.
• Text Logo (data.text_logo): If logo_link is not provided or the image fails to load, and text_logo is set, this text will be displayed as a prominent heading where the logo would normally appear.

If neither is provided, the logo area will typically be left blank, or a default document title might appear depending on the template.

Feature: QR Codes

A QR code can be added to the invoice, typically used for payment links or links to online invoice versions.

• URL (data.qr_link): A valid URL that the QR code will point to when scanned. If omitted, no QR code is generated.
• Description (data.qr_desc): Optional text displayed beneath the QR code (e.g., "Scan to Pay").
• Position (data.qr_position): Can be "top" (on a separate page before the invoice content) or "bottom" (on a separate page after the invoice content, default).

Feature: Translations & Text

The API provides flexibility in how static text elements (like "Due Date", "Subtotal", etc.) are displayed on the PDF.

1. Base Language (data.language)

The data.language field (e.g., "en", "es", "de") determines the base set of translations. The API attempts to load a corresponding language file (e.g., lang_en.json, lang_es.json) from its internal collection. If a specific language file isn't found, it defaults to English (lang_en.json).

An example structure of the default lang_en.json is:

{
  "from": "From",
  "to": "To",
  "id_invoice": "Invoice #",
  "invoice_of": "Invoice Date",
  "due_date": "Due Date",
  "subject": "Subject",
  "item_type": "Type",
  "description": "Description",
  "quantity": "Qty",
  "unit_price": "Unit Price",
  "totals": "Amount",
  "note": "Note",
  "free": "Free",
  "subtotal": "Subtotal",
  "discount": "Discount",
  "amount_to_be_paid": "Amount to be Paid",
  "rounding_difference": "Rounding Adjustment"
}

2. Per-Request Overrides (top-level lang object)

You can override any of these base translations for a specific invoice by providing a lang object at the top level of your request body (as a sibling to the data object). Keys in this lang object will replace the corresponding keys from the loaded base language file for that specific request.

Example of Overriding Text:

If your data.language is "en", but for a particular invoice you want "Due Date" to appear as "Payment Expected By" and "Item Type" as "Category", your request body would look like this:

{
  "data": {
    "language": "en",
    // ... other data fields ...
    "invoice": {
      // ... invoice fields ...
    }
  },
  "lang": {
    "due_date": "Payment Expected By",
    "item_type": "Category",
    "custom_key_if_template_supports_it": "Custom Value" 
  }
}

This provides fine-grained control over the text displayed on your invoices without needing to modify base language files globally.

Example Payload & API Calls

This section provides a complete example JSON payload (specifically, the content for the data key) and demonstrates how to send it to the API using various programming languages. Remember to replace YOUR_CLIENT_API_KEY_HERE with your valid client API key.

Full Example data Object Payload:

This payload showcases many available fields, including the new rounding feature and an omitted optional field (to.street). Your actual payload might be simpler. This example adheres to US conventions for currency, locale, and formatting.

{
  "language": "en",
  "babel_locale": "en_US",
  "timezone": "America/New_York",
  "decimal_separator": ".",
  "thousands_separator": ",",
  "use_int_for_currency": false,
  "qr_position": "bottom",
  "from": {
    "name": "USA Example Corp.",
    "street": "100 Main Street",
    "place": "New York, NY 10001",
    "country": "United States",
    "extra": "Suite 500",
    "address_lines_order": ["name", "extra", "street", "place", "country"]
  },
  "to": {
    "name": "Client Solutions Inc.",
    "place": "Los Angeles, CA 90012",
    "country": "United States",
    "extra": "Attn: Accounts Payable"
  },
  "text_logo": "USA Example",
  "qr_link": "https://example.com/invoice/INV-2024-001/pay",
  "qr_desc": "Scan to view or pay your invoice",
  "logo_link": "https://raw.githubusercontent.com/贄Dev/PublicElements/main/logo_placeholder_250x60_dark.png",
  "logo_max_height": 60,
  "logo_max_width": 250,
  "logo_min_height": 40,
  "invoice": {
    "id": "INV-2024-001",
    "purchase_order": "PO-CLIENT-12345",
    "currency": "USD",
    "discount_amount": "25.00",
    "discount_percentage": "2.5",
    "taxes_method": "excluded",
    "date_timestamp": 1721001600,
    "due_date": "August 15, 2024",
    "date_format": "MMMM d, yy",
    "subject": "Q3 Software Development Services",
    "notes": "Thank you for your business! Payment is due within 30 days of the invoice date. Please reference invoice ID with your payment.",
    "taxes": [
      {"name": "State Sales Tax", "value": "6.25"},
      {"name": "Local Surcharge", "value": "0.5"}
    ],
    "items": [
      {
        "item_type": "Service",
        "description": "Software Development Hours (Task A)",
        "quantity": "80",
        "unit_price": "125.00",
        "taxes": [1, 0]
      },
      {
        "item_type": "Product",
        "description": "Annual Software License - Tier 2",
        "quantity": "1",
        "unit_price": "1500.00",
        "total": "1450.00",
        "taxes": [1, 1]
      }
    ],
    "rounding_target_cents": 5,
    "rounding_method": "closest"
  }
}

When sending this to the API, it should be wrapped within a top-level JSON object under the "data" key, like so: { "data": { "language": "en", "babel_locale": "en_US", ... } }. The code examples below handle this wrapping.

Sending the Payload:

const API_URL = 'https://api.json2invoice.com';
const API_KEY = 'YOUR_CLIENT_API_KEY_HERE';
const invoiceData = {
  "language": "en",
  "babel_locale": "en_US",
  "timezone": "America/New_York",
  "decimal_separator": ".",
  "thousands_separator": ",",
  "use_int_for_currency": false,
  "qr_position": "bottom",
  "from": {
    "name": "USA Example Corp.",
    "street": "100 Main Street",
    "place": "New York, NY 10001",
    "country": "United States",
    "extra": "Suite 500",
    "address_lines_order": ["name", "extra", "street", "place", "country"]
  },
  "to": {
    "name": "Client Solutions Inc.",
    "place": "Los Angeles, CA 90012",
    "country": "United States",
    "extra": "Attn: Accounts Payable"
  },
  "text_logo": "USA Example",
  "qr_link": "https://example.com/invoice/INV-2024-001/pay",
  "qr_desc": "Scan to view or pay your invoice",
  "logo_link": "https://raw.githubusercontent.com/贄Dev/PublicElements/main/logo_placeholder_250x60_dark.png",
  "logo_max_height": 60,
  "logo_max_width": 250,
  "logo_min_height": 40,
  "invoice": {
    "id": "INV-2024-001",
    "purchase_order": "PO-CLIENT-12345",
    "currency": "USD",
    "discount_amount": "25.00",
    "discount_percentage": "2.5",
    "taxes_method": "excluded",
    "date_timestamp": 1721001600,
    "due_date": "August 15, 2024",
    "date_format": "MMMM d, yy",
    "subject": "Q3 Software Development Services",
    "notes": "Thank you for your business! Payment is due within 30 days of the invoice date. Please reference invoice ID with your payment.",
    "taxes": [
      {"name": "State Sales Tax", "value": "6.25"},
      {"name": "Local Surcharge", "value": "0.5"}
    ],
    "items": [
      {
        "item_type": "Service",
        "description": "Software Development Hours (Task A)",
        "quantity": "80",
        "unit_price": "125.00",
        "taxes": [1, 0]
      },
      {
        "item_type": "Product",
        "description": "Annual Software License - Tier 2",
        "quantity": "1",
        "unit_price": "1500.00",
        "total": "1450.00",
        "taxes": [1, 1]
      }
    ],
    "rounding_target_cents": 5,
    "rounding_method": "closest"
  }
};

async function generatePdf() {
  try {
    const response = await fetch(API_URL, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'X-API-Key': API_KEY },
      body: JSON.stringify({ data: invoiceData })
    });
    const result = await response.json();
    if (response.ok) {
      console.log("Success:", result);
    } else {
      console.error("Error:", response.status, result);
    }
  } catch (error) {
    console.error('Request failed:', error);
  }
}
generatePdf();

Detailed API Responses

Success Response (200 OK)

Upon successful PDF generation and upload to our secure storage, the API will return a JSON object with the following structure:

{
  "message": "PDF generated and uploaded successfully.",
  "url": "https://pdf.json2invoice.com/INV-2024-001_timestamp_uuid.pdf"
}

Note: The URL structure is illustrative; the actual filename will include a unique timestamp and identifier. The domain pdf.json2invoice.com is the correct one for accessing generated PDFs.

If invoice total rounding was applied (via rounding_target_cents) and resulted in a change to the total, a line item such as "Rounding Adjustment" will be visible in the PDF's summary section, showing the difference.

Fields:

Error Responses

400 Bad Request: Invalid Input

This status code indicates an issue with the data sent by your application. Common causes include:

• Missing or Malformed JSON:

  { "error": "No data provided." }

  { "error": "Invalid JSON format: <parsing error details>" }

• Missing data Key: The top-level request object must contain a data key.

  { "error": "Missing 'data' key in payload." }

• Payload Validation Errors: The content of the data object failed validation against the defined schema.

  {
    "error": "Invalid payload structure",
    "details": [ /* Array of Pydantic validation error objects */ ]
  }

  The details array is crucial for debugging. It provides specific information about each validation failure:

  For 400 Bad Request (Invalid Payload Structure)

  Property	Description	Type	Default
  error	General error message indicating a problem with the submitted data.	string	"Invalid payload structure"
  details	An array providing specific details about each validation error encountered.	array of objects	-
  details[].loc	Indicates the location (path) of the field within the input payload that caused the error (e.g., ["invoice", "items", 0, "quantity"]).	array	-
  details[].msg	A human-readable message describing the validation error.	string	-
  details[].type	The type of validation error (e.g., "value_error.decimal.finite", "missing").	string	-

403 Forbidden: Authentication or Authorization Issue

This error signifies that your request was understood, but the server is refusing to fulfill it due to authentication or authorization problems.

• Missing, Invalid, or Unauthorized API Key:

  { "error": "Forbidden: Missing or invalid API Key." }

  {
    "error": "Forbidden: Missing or incomplete authentication context."
  }

500 Internal Server Error: Server-Side Problem

This indicates an unexpected issue occurred on our server while attempting to process your request (e.g., during PDF rendering, file storage, or other internal operations).

{
  "error": "An unexpected error occurred while processing your request.",
  "trace": "Internal server error. Check logs." 
}

If our server is in a special debug mode (not typical for production), the trace might contain more detailed error information. Otherwise, please refer to server logs or contact support with any provided request identifiers or timestamps.

Note on Partial Success

In a rare scenario where the PDF is successfully generated and stored, but a subsequent, non-critical internal operation (like decrementing an API usage credit) fails, the API will still return a 200 OK response with the PDF URL. This ensures you receive your generated document. A critical warning will be logged on our server for this situation, which we will investigate.