Introduction
In Odoo, models define how data is structured and stored in the database. Every piece of business data you work with, from sales orders to invoices to contacts, lives in a model.
Understanding Odoo models is essential for both developers and functional consultants. Models are the foundation of the Odoo data architecture. They define fields, relationships, and business logic.
This article focuses on one of the most important models in Odoo: res.partner. Whether you are building custom modules, integrating external systems, or configuring workflows, you will work with this model.
What is the res.partner Model
The res.partner model represents contacts, customers, vendors, and companies in Odoo. It is the central place where all party information is stored.
This model in Odoo is used across almost every module. Sales, CRM, invoicing, purchase, and e-commerce all reference res.partner. When you create a customer in Sales, a lead in CRM, or a vendor in Purchase, you are creating or linking to a res.partner record.
The model is defined in the base module. Other modules extend it through Odoo model inheritance. CRM adds lead-related fields. Accounting adds credit and payment terms. Each module adds what it needs without duplicating the core structure.
Key Fields in the Model
Here are the most important Odoo fields in the res.partner model. Understanding these will help you work effectively with contacts and partners.
1. name
Type: Char. This field stores the name of the record. For a company, it is the company name. For a person, it is the full name. It is displayed in many Odoo views and is the primary identifier for the partner.
2. create_date
Type: Datetime. Stores the date and time when the record was created. Automatically managed by Odoo. Useful for reporting and auditing.
3. write_date
Type: Datetime. Stores the date and time of the last modification. Also automatically managed. Helps track when data was last updated.
4. email
Type: Char. The primary email address. Used for communications, invoicing, and portal access. Odoo validates email format when possible.
5. phone
Type: Char. The main phone number. Displayed in contact forms and used for communication workflows.
6. mobile
Type: Char. Mobile phone number. Often used for SMS or urgent notifications when different from the main phone.
7. street
Type: Char. The first line of the address. Part of the standard address block used on documents and forms.
8. street2
Type: Char. The second line of the address. Used for apartment numbers, building names, or additional address details.
9. city
Type: Char. The city or town. Address formatting can vary by country.
10. zip
Type: Char. Postal or ZIP code. Used for address validation and shipping calculations.
11. state_id
Type: Many2one (res.country.state). The state or province. The domain is filtered by country. Not all countries use states.
12. country_id
Type: Many2one (res.country). The country. Drives address formatting, tax rules, and localization.
13. is_company
Type: Boolean. Indicates whether the record is a company or a person. Companies can have child contacts. Persons can be linked to a company via parent_id.
14. parent_id
Type: Many2one (res.partner). For contact records, this links to the related company. Enables the company-contact hierarchy. When set, address and other fields can inherit from the parent.
15. child_ids
Type: One2many (res.partner). The inverse of parent_id. Lists all contacts belonging to a company. Used to navigate from a company to its contacts.
16. company_id
Type: Many2one (res.company). In multi-company setups, this indicates which Odoo company the partner belongs to. Affects record visibility and access.
17. vat
Type: Char. Tax ID or VAT number. Validated by country format. Use a slash to indicate the partner is not subject to tax. Important for invoicing and compliance.
18. customer_rank
Type: Integer. Indicates customer status. Odoo increments this when the partner has sales. Used to filter and prioritize customers in lists and reports.
19. supplier_rank
Type: Integer. Indicates supplier status. Incremented when the partner has purchase orders or bills. Used to identify vendors.
20. user_id
Type: Many2one (res.users). The salesperson or responsible user. Used for CRM, sales teams, and activity assignment.
21. type
Type: Selection. Address type for child contacts: Contact, Invoice, Delivery, or Other. Determines which address is used on documents. Only relevant for contacts under a company.
22. ref
Type: Char. Internal reference or code. Useful for external system mapping and custom numbering.
23. website
Type: Char. Website URL. Used on the contact form and in e-commerce contexts.
24. comment
Type: Html. Internal notes. Visible to internal users. Often used for sales notes or special instructions.
25. active
Type: Boolean. Soft delete flag. When False, the record is archived and hidden from default views. Records are not physically deleted.
26. lang
Type: Selection. Preferred language. Emails and documents sent to this partner can be translated. Inherited from parent when applicable.
27. image_1920
Type: Binary. Partner image or logo. Odoo stores multiple sizes. Used in forms, reports, and the website.
28. category_id
Type: Many2many (res.partner.category). Tags or categories. Used for segmentation, filtering, and marketing. Flexible for custom classification.
How This Model Is Used in Business Workflows
1. Sales and CRM
When a salesperson creates a quotation, they select a customer from res.partner. The same partner record is used for the lead, opportunity, and order. Customer rank and user_id drive reporting and assignment.
2. Invoicing
Invoices and bills reference a partner for the billing address. The vat field is used for tax calculations. Credit limit and payment terms are often stored on the partner.
3. Purchase and Vendors
Purchase orders and vendor bills link to res.partner. Supplier rank identifies active vendors. The buyer_id field assigns a responsible user for vendor management.
4. E-commerce and Portal
Website visitors can create partner records when registering. Those records are used for orders, quotes, and portal access. Address and contact details come from the partner.
5. Multi-Company and Consolidation
In multi-company setups, the same legal entity can exist as different partner records per company. The company_id field and inter-company rules determine how data is shared.
How Developers Extend This Model
Developers extend res.partner using several patterns. Odoo model inheritance is the main mechanism.
Model Inheritance
Use _inherit = 'res.partner' to extend the model. Add new fields, override methods, or add constraints. The inherit model in Odoo keeps your changes in a separate module for easy upgrades.
Adding Fields
Define new Odoo fields in your inherited model. Use the right field type: Char, Many2one, Boolean, Integer, Text, Selection. Consider company-dependent fields for multi-company.
Python Extensions
Override create, write, or unlink to add logic. Use super() to call the original. Be careful with computed fields and their dependencies.
Odoo Studio
Odoo Studio lets you add fields without code. Good for quick customizations. For complex logic or upgrades, custom modules are more maintainable.
Best Practices
- Use the company-contact hierarchy correctly. Create the company first, then add contacts with parent_id.
- Set country_id for proper address formatting and tax handling.
- Use commercial_partner_id when you need the top-level entity for grouping (e.g. for credit or reporting).
- When building API integrations, use the XML-RPC or JSON-RPC API. The res.partner model is fully exposed. Map external IDs carefully.
- For custom fields, use the
x_prefix or a module prefix to avoid conflicts with future Odoo versions.
Common Mistakes
- Creating duplicate partners instead of searching for existing ones. Use
email_normalizedorreffor deduplication. - Mixing up parent_id and company_id. parent_id is for the contact-company link. company_id is for multi-company Odoo.
- Forgetting to set type on child contacts. Invoice and delivery addresses need the correct type for documents.
- Overriding core methods without calling super(). This can break other modules or future upgrades.
- Adding required custom fields without defaults. Existing records will fail validation on upgrade.
Conclusion
The res.partner model is central to Odoo. It stores contacts, customers, and vendors. Understanding its fields and how modules extend it will help you configure, customize, and integrate Odoo effectively.
Whether you are a functional consultant mapping business processes or a developer building custom modules, a solid grasp of res.partner will save time and prevent errors.
Need Help With Your Odoo Implementation?
Dasolo helps companies implement, customize, and optimize Odoo. We specialize in API integrations and Odoo development. Our team has deep experience with the Odoo data architecture and models like res.partner.
If you need help with your Odoo implementation, custom modules, or integrations, we are here to help. Book a demo to discuss your project.