Custom Paper Format in Odoo QWeb Reports

Odoo's QWeb engine renders PDF reports using a paper format that controls page size, orientation, margins, and the space reserved for headers and footers. The default paper format (A4 portrait) suits most standard documents — invoices, purchase orders, delivery slips. When a business needs a custom document size, a landscape layout, or specific margin widths for pre-printed stationery, a custom paper format is required.

This guide covers three approaches: configuring a paper format through the Odoo UI, binding it to a report action in XML, and overriding it directly in a QWeb report template. All three approaches are compatible and can be combined.

What Is a Paper Format in Odoo?

A paper format in Odoo is a record in the `ir.paper.format` model that defines the physical and layout properties of a printed PDF page. Every `ir.actions.report` (report action) has a `paper_format_id` field — when that field is empty, the report falls back to the company default format.

Create a Custom Paper Format via the Odoo UI

1. Navigate to Settings → Technical → Reporting → Paper Formats.
2. Click New.
3. Set Name to a descriptive identifier (e.g. "Invoice A4 Narrow Margin").
4. Choose Format (A4, A3, Letter, Legal) or leave it blank if you will set custom dimensions via Page Width / Page Height.
5. Set Orientation to Portrait or Landscape.
6. Set the four margin fields (Top, Bottom, Left, Right) in mm. A safe starting point for invoices is 10 / 10 / 10 / 10.
7. Set Header Spacing in mm. This controls the gap between the page top edge and where body content begins. Start with the height of your header in mm and add 5–10 mm buffer.
8. Save the record. The paper format is now available in the Paper Format dropdown of any report action.

Bind a Paper Format to a Report Action in XML

For custom modules, define both the paper format record and the report action binding in XML data files. This approach is repeatable, version-controlled, and installs correctly on any Odoo instance.

Step 1 — Define the paper format record

<!-- data/paper_format_data.xml -->
<odoo>
  <record id="paperformat_invoice_custom" model="ir.paper.format">
    <field name="name">Invoice A4 Narrow Margin</field>
    <field name="default" eval="False"/>
    <field name="format">A4</field>
    <field name="orientation">Portrait</field>
    <field name="margin_top">10.0</field>
    <field name="margin_bottom">10.0</field>
    <field name="margin_left">10.0</field>
    <field name="margin_right">10.0</field>
    <field name="header_line" eval="False"/>
    <field name="header_spacing">40</field>
  </record>
</odoo>

Step 2 — Bind the paper format to the report action

<!-- report/account_invoice_report.xml -->
<odoo>
  <!-- Define the report action and reference the paper format -->
  <report
    id="account_invoices_custom"
    model="account.move"
    string="Custom Invoice"
    report_type="qweb-pdf"
    name="your_module.report_invoice_custom_document"
    file="your_module.report_invoice_custom_document"
    paper_format="your_module.paperformat_invoice_custom"
    print_report_name="(object.name or 'Invoice')"
  />
</odoo>

QWeb Report Template — Header, Footer, and Body Layout

The paper format controls the available print area. The QWeb report template controls what renders within that area. The three parts — header, footer, and body — are defined using specific `t-call` inheritance points in Odoo's base report layout.

<!-- report/report_invoice_custom_document.xml -->
<odoo>
  <!-- Outer wrapper must inherit web.html_container -->
  <template id="report_invoice_custom_document">
    <t t-call="web.html_container">
      <t t-foreach="docs" t-as="doc">
        <t t-call="web.external_layout">
          <t t-set="doc" t-value="doc.with_context(lang=doc.partner_id.lang)"/>

          <!-- Body content goes here -->
          <div class="page">
            <h2 t-field="doc.name"/>
            <p t-field="doc.invoice_date"/>
            <!-- ... your report body ... -->
          </div>

        </t>
      </t>
    </t>
  </template>
</odoo>

Custom header and footer templates

Odoo renders headers and footers via `web.external_layout_header` and `web.external_layout_footer`. To replace them for a specific report, inherit these templates and restrict the override with `t-if` on the `report_name` variable.

<!-- Custom header for a specific report only -->
<template id="report_invoice_custom_header"
          inherit_id="web.external_layout_header">
  <xpath expr="//div[hasclass('header')]" position="replace">
    <!-- Only override for our custom report -->
    <t t-if="report_name == 'your_module.report_invoice_custom_document'">
      <div class="header" style="height: 35mm;">
        <!-- Your custom header HTML here -->
        <img t-att-src="'/web/image/res.company/%s/logo' % company.id"
             style="max-height: 30mm;"/>
        <div class="text-right">
          <strong t-field="company.name"/>
        </div>
      </div>
    </t>
    <t t-else="">
      <!-- Fall back to default header for all other reports -->
      <t t-call="web.external_layout_standard_header"/>
    </t>
  </xpath>
</template>

Common Paper Format Issues and Fixes

Version Notes and Spot-Check Guide

iWesabe Editorial Team

Practitioner insights on Odoo ERP, ZATCA compliance, and Saudi enterprise digital operations — written by iWesabe's consulting, finance, and engineering teams.

About iWesabe