Master Odoo Amount to Words: Essential Guide for Seamless Financial Documents

Have you ever found yourself wishing your Odoo financial documents, like sales orders or invoices, could display monetary figures not just as digits, but as clearly spelled-out words? Imagine the enhanced clarity, reduced potential for error, and heightened professionalism that comes with such a feature. This isn’t just a nicety; for many businesses, converting Odoo amount to words is a crucial requirement for compliance, auditing, and ensuring absolute clarity in transactions.

In this comprehensive guide, we’ll delve into how you can effortlessly implement the Odoo amount to words functionality across your Sales, Accounting (Invoices), and Purchase modules. The best part? We’ll achieve this using Odoo’s powerful built-in capabilities, meaning no external dependencies or complex libraries are needed. You’ll learn the step-by-step process to transform numerical values into their word representations, enhancing the readability and accuracy of your documents.

For a visual walkthrough of this process, you can refer to the original tutorial that inspired this guide: Odoo Digits to Words Exercise Solution.

Why Odoo Amount to Words is Indispensable for Your Business

Implementing Odoo amount to words isn’t merely a cosmetic change; it brings substantial benefits to your business operations:

• Enhanced Readability and Clarity: Financial documents often pass through many hands – from sales teams to finance departments, and ultimately to clients or vendors. Displaying the Odoo amount to words alongside the numerical value drastically improves comprehension, especially for complex figures or in situations where numbers might be misread. This clarity minimizes confusion and speeds up verification processes.
• Reduced Errors and Misinterpretations: A common source of errors in manual data entry or document processing is misreading digits. By providing the amount in both numeric and word forms, you create a robust cross-verification mechanism, significantly reducing the chances of costly mistakes and discrepancies. This double-check system is a powerful safeguard against financial blunders.
• Professionalism and Compliance: Many legal and financial regulations, particularly in certain regions or for specific types of transactions (like checks, proforma invoices, or official tenders), require monetary values to be spelled out in words. Incorporating Odoo amount to words ensures your documents meet these professional and compliance standards, fostering trust and preventing legal issues.
• Streamlined Auditing and Record-Keeping: Auditors and accountants appreciate the added layer of transparency that amounts in words provide. It makes auditing processes smoother, as figures are unequivocally presented, leading to quicker approvals and easier reconciliation. This meticulous record-keeping strengthens your financial backbone.
• Improved User Experience (UX): For both internal users and external partners, receiving documents with clearly spelled-out amounts improves the overall user experience. It reflects attention to detail and a commitment to precision, reinforcing your company’s professional image.

The Hidden Gem: Odoo’s amount_to_text Method

The beauty of achieving Odoo amount to words conversion lies in an often-overlooked, yet incredibly powerful, built-in method within Odoo itself: amount_to_text. This method is an integral part of Odoo’s currency handling capabilities, designed specifically to convert numerical monetary values into their corresponding word representations, taking into account the currency associated with the amount.

This means you don’t need to scour for external libraries, write complex algorithms for number-to-word conversion, or worry about multi-language or multi-currency nuances. Odoo’s amount_to_text method intelligently handles these complexities, automatically adjusting for the currency (e.g., “Dollars,” “Rupees,” “Euros”) and even specific regional conventions (like “cents” or “paise”). It’s truly a hidden gem that makes the process of adding Odoo amount to words functionality remarkably straightforward.

Step-by-Step Tutorial: Implementing Odoo Amount to Words

Let’s dive into the practical implementation. We’ll walk through adding this feature to your Sales Orders, Invoices, and Purchase Orders.

Prerequisites:

• An active Odoo environment (e.g., Odoo 17, Odoo 16, or Odoo 15).
• Developer mode activated in your Odoo instance.
• Basic understanding of Odoo module development (Python and XML).

Phase 1: Module Setup and Field Definition (Python)

First, you’ll need a custom module or an existing one where you can add your modifications. We will inherit the relevant models (sale.order, account.move, purchase.order) and add a computed field to store the amount in words.

1. Create/Identify Your Custom Module:
Ensure you have a custom module (e.g., my_custom_module) in your Odoo addons path. Inside, create a models directory and an __init__.py file within it, plus a Python file (e.g., models.py).

2. Inherit Models and Define the Computed Field:

In your models.py file, you’ll add the following Python code. This code inherits the sale.order, account.move, and purchase.order models and adds a new Char field named amount_in_words that will be computed.

# models.py
from odoo import fields, models, api

class SaleOrder(models.Model):
    _inherit = 'sale.order'

    amount_in_words = fields.Char(
        string="Amount in Words",
        compute='_compute_amount_in_words',
        store=True, # Set to True if you want to store the computed value for faster access
        help="The total amount in words, automatically calculated based on the total amount and currency."
    )

    @api.depends('amount_total', 'currency_id')
    def _compute_amount_in_words(self):
        for record in self:
            if record.currency_id and record.amount_total:
                # This is the core method for Odoo amount to words conversion
                record.amount_in_words = record.currency_id.amount_to_text(record.amount_total)
            else:
                record.amount_in_words = ""

class AccountMove(models.Model):
    _inherit = 'account.move'

    amount_in_words = fields.Char(
        string="Amount in Words",
        compute='_compute_amount_in_words',
        store=True,
        help="The total amount in words for the invoice, automatically calculated."
    )

    @api.depends('amount_total', 'currency_id')
    def _compute_amount_in_words(self):
        for record in self:
            if record.currency_id and record.amount_total:
                record.amount_in_words = record.currency_id.amount_to_text(record.amount_total)
            else:
                record.amount_in_words = ""

class PurchaseOrder(models.Model):
    _inherit = 'purchase.order'

    amount_in_words = fields.Char(
        string="Amount in Words",
        compute='_compute_amount_in_words',
        store=True,
        help="The total amount in words for the purchase order, automatically calculated."
    )

    @api.depends('amount_total', 'currency_id')
    def _compute_amount_in_words(self):
        for record in self:
            if record.currency_id and record.amount_total:
                record.amount_in_words = record.currency_id.amount_to_text(record.amount_total)
            else:
                record.amount_in_words = ""

Important Note: The store=True attribute is optional. If set to True, the computed value will be stored in the database, potentially speeding up report generation and searches but requiring a recompute on value changes. If False, it’s computed on-the-fly when accessed. For Odoo amount to words fields, storing can be beneficial.

Phase 2: Integrating into Form Views (XML)

Next, we’ll make our newly created amount_in_words field visible on the respective form views. You’ll need to create or modify XML files in your module’s views directory (e.g., views/sale_order_views.xml, views/account_move_views.xml, views/purchase_order_views.xml).

1. Sales Order Form View:

Add or update your sale_order_views.xml (or similar) file:

<!-- views/sale_order_views.xml -->
<odoo>
    <record id="sale_order_form_view_inherit_amount_words" model="ir.ui.view">
        <field name="name">sale.order.form.inherit.amount.words</field>
        <field name="model">sale.order</field>
        <field name="inherit_id" ref="sale.view_order_form"/>
        <field name="arch" type="xml">
            <!-- Example: Add after the 'Customer Reference' field in the 'Other Information' tab -->
            <xpath expr="//field[@name='client_order_ref']" position="after">
                <field name="amount_in_words" class="oe_read_only" string="Total Amount in Words"/>
            </xpath>
            <!-- Alternatively, add after the 'Payment Terms' field for better visibility -->
            <!-- <xpath expr="//field[@name='payment_term_id']" position="after">
                <field name="amount_in_words" class="oe_read_only" string="Total Amount in Words"/>
            </xpath> -->
        </field>
    </record>
</odoo>

2. Invoice Form View:

Add or update your account_move_views.xml (or similar) file:

<!-- views/account_move_views.xml -->
<odoo>
    <record id="account_move_form_view_inherit_amount_words" model="ir.ui.view">
        <field name="name">account.move.form.inherit.amount.words</field>
        <field name="model">account.move</field>
        <field name="inherit_id" ref="account.view_move_form"/>
        <field name="arch" type="xml">
            <!-- Example: Add after the 'Narration' field (Terms and Conditions) -->
            <xpath expr="//field[@name='narration']" position="after">
                <field name="amount_in_words" class="oe_read_only" string="Total Amount in Words"/>
            </xpath>
        </field>
    </record>
</odoo>

3. Purchase Order Form View:

Add or update your purchase_order_views.xml (or similar) file:

<!-- views/purchase_order_views.xml -->
<odoo>
    <record id="purchase_order_form_view_inherit_amount_words" model="ir.ui.view">
        <field name="name">purchase.order.form.inherit.amount.words</field>
        <field name="model">purchase.order</field>
        <field name="inherit_id" ref="purchase.purchase_order_form"/>
        <field name="arch" type="xml">
            <!-- Example: Add after the 'Payment Terms' field -->
            <xpath expr="//field[@name='payment_term_id']" position="after">
                <<field name="amount_in_words" class="oe_read_only" string="Total Amount in Words"/>
            </xpath>
        </field>
    </record>
</odoo>

Phase 3: Displaying in QWeb Reports (XML)

The true value of Odoo amount to words often shines brightest on printed documents like PDFs. We’ll modify the QWeb report templates for Sales, Invoices, and Purchases to include our new field.

1. Sales Order Report:

Modify the sales order report template. Typically, this is sale.report_saleorder_document.

<!-- views/report_saleorder.xml (or similar) -->
<odoo>
    <template id="report_saleorder_document_inherit_amount_words" inherit_id="sale.report_saleorder_document">
        <xpath expr="//div[@id='total']" position="after">
            <div class="clearfix">
                <div class="row">
                    <div class="col-xs-12">
                        <p class="text-left">
                            <strong>Amount in Words:</strong> <span t-esc="doc.amount_in_words.capitalize()"/>
                        </p>
                    </div>
                </div>
            </div>
        </xpath>
    </template>
</odoo>

2. Invoice Report:

Modify the invoice report template. The main template is account.report_invoice_document. Note the use of o instead of doc for the record object in invoice reports.

<!-- views/report_invoice.xml (or similar) -->
<odoo>
    <template id="report_invoice_document_inherit_amount_words" inherit_id="account.report_invoice_document">
        <xpath expr="//div[@id='total']" position="after">
            <div class="clearfix">
                <div class="row">
                    <div class="col-xs-12">
                        <p class="text-left">
                            <strong>Amount in Words:</strong> <span t-esc="o.amount_in_words.capitalize()"/>
                        </p>
                    </div>
                </div>
            </div>
        </xpath>
    </template>
</odoo>

3. Purchase Order Report:

Modify the purchase order report template. Typically, this is purchase.report_purchaseorder_document.

<!-- views/report_purchaseorder.xml (or similar) -->
<odoo>
    <template id="report_purchaseorder_document_inherit_amount_words" inherit_id="purchase.report_purchaseorder_document">
        <xpath expr="//div[@id='total']" position="after">
            <div class="clearfix">
                <div class="row">
                    <div class="col-xs-12">
                        <p class="text-left">
                            <strong>Amount in Words:</strong> <span t-esc="o.amount_in_words.capitalize()"/>
                        </p>
                    </div>
                </div>
            </div>
        </xpath>
    </template>
</odoo>

Phase 4: Installation and Testing

1. Update __manifest__.py:
Ensure all your new XML files are included in your custom module’s __manifest__.py file under the data key.

# __manifest__.py
{
    'name': 'Amount in Words for Odoo Documents',
    'version': '1.0',
    'summary': 'Converts numerical amounts to words in Sales, Invoices, and Purchase documents.',
    'description': """
        Adds a computed field to display the amount in words on Sales Orders,
        Customer Invoices, and Purchase Orders, both on the form view and in printed reports.
        Leverages Odoo's built-in amount_to_text method for multi-currency support.
    """,
    'author': 'Your Name/Company',
    'website': 'https://www.yourwebsite.com/odoo-amount-to-words-guide', # Placeholder URL
    'category': 'Sales/Accounting',
    'depends': ['sale_management', 'account', 'purchase'],
    'data': [
        'views/sale_order_views.xml',
        'views/account_move_views.xml',
        'views/purchase_order_views.xml',
        'views/report_saleorder.xml',
        'views/report_invoice.xml',
        'views/report_purchaseorder.xml',
    ],
    'installable': True,
    'application': False,
    'auto_install': False,
    'license': 'LGPL-3',
}

2. Install/Upgrade the Module:
Go to your Odoo Apps list, search for your module, and click “Install” or “Upgrade” if it’s already installed. Remember to restart your Odoo service if you made changes to Python files.

3. Test the Functionality:

• Sales Order: Create a new sales order or open an existing one. You should see the “Amount in Words” field on the form view. Print the sales order report to PDF, and verify the amount is spelled out.
• Invoice: Create a new invoice (Customer Invoice) or open an existing one. Check the form view and print the invoice report.
• Purchase Order: Create a new purchase order. Verify the form view and print the report.

Observe how the Odoo amount to words field correctly displays the amount in text, including the currency, automatically.

Handling Multi-Currency with Odoo Amount to Words

One of the significant advantages of using Odoo’s native amount_to_text method for Odoo amount to words conversion is its inherent support for multi-currency environments. You don’t need to write any special logic to handle different currencies.

The amount_to_text method is called on the currency_id object (record.currency_id.amount_to_text(...)). This means Odoo intelligently knows which currency’s rules to apply for the word conversion. Whether your sale order is in USD, an invoice in INR, or a purchase order in EUR, the system will correctly spell out “Dollars,” “Rupees,” or “Euros” along with the numeric amount, provided your currencies are properly configured in Odoo (Accounting -> Configuration -> Currencies).

This robust multi-currency capability simplifies development and ensures global applicability of your documents, making Odoo amount to words a truly versatile feature.

Troubleshooting Common Issues

While implementing Odoo amount to words is straightforward, you might encounter a few common issues:

• Incorrect XPath: XML xpath expressions are very specific. If your field isn’t appearing on the form or report, double-check your expr and position attributes. Use Odoo’s developer mode (technical features) to inspect the exact XML structure of the original views to get the correct path.
• Wrong External ID: When inheriting views or reports (inherit_id), ensure the ref attribute points to the correct external ID of the base view/template you intend to modify. An incorrect ID will prevent your inheritance from working.
• doc vs. o in Reports: As noted in the tutorial, Odoo QWeb reports often use different variables to refer to the main record. For sales orders, doc is common. For invoices and purchase orders, o is frequently used. Using the wrong variable will lead to a KeyError or AttributeError. Always verify which variable holds the main record context for the specific report you’re modifying.
• Module Not Upgraded: After making changes to Python or XML files, you must upgrade your custom module in Odoo to apply these changes. Simply restarting the Odoo service is not enough for XML changes or new Python files.
• Missing Dependencies: Ensure your __manifest__.py file correctly lists sale_management, account, and purchase in the depends key, as you are inheriting models from these modules.

Beyond the Basics: Advanced Customizations

The principles for implementing Odoo amount to words can be extended to virtually any Odoo model that deals with monetary values and has an associated currency. Consider applying this feature to:

• Payment Records: Displaying payment amounts in words for receipts or payment confirmations.
• Journal Entries: Adding word representation to financial journal entries for enhanced audit trails.
• Custom Documents: Any custom reports or documents where clarity of financial figures is paramount.

The process remains consistent: inherit the model, add a computed Char field using currency_id.amount_to_text(), and then integrate this field into your desired form views and QWeb reports.

Conclusion: Empowering Your Odoo Documents

Implementing Odoo amount to words is a small but powerful enhancement that significantly boosts the clarity, professionalism, and accuracy of your financial documents. By leveraging Odoo’s robust amount_to_text method, you can achieve this critical functionality without needing complex custom development or external libraries. This tutorial has provided you with a clear, step-by-step path to integrate this feature into your Sales Orders, Invoices, and Purchase Orders, ensuring your business communicates financial figures with unparalleled precision.

Take control of your Odoo documents and transform them into even more effective communication tools. This essential feature will not only streamline your internal processes but also elevate your interactions with clients and vendors.

Ready to deepen your Odoo expertise? Explore more of our Odoo Development Tutorials for practical guides and tips. For more in-depth technical details on Odoo’s framework, refer to the Odoo Official Documentation.

If you have any questions or run into challenges, feel free to comment below or reach out to our team for expert assistance!