Odoo Field Types – General JSON API Guide

📘 Odoo Field Types – General JSON API Guide​

This document references the expected JSON value format for all standard Odoo field types when constructing JSON payloads for the Odoo API (create, write, etc.).

1. Basic Field Types​

These fields accept simple, singular values.

2. Relation Field Types​

These fields link to other records. The values for many2many and one2many are special Odoo command tuples.

Odoo Command Syntax Reference​

3. Special Field Types​

These fields handle complex or non-standard data structures.

4. Key Notes for API Users​

• Direct Key-Value: Send field names as keys and the expected value format as the value directly in the JSON body.
• Relations: many2one uses a simple integer ID. many2many and one2many require command tuples for any modifications to the linked records.
• Date/Time: Use ISO 8601 strings for both date (YYYY-MM-DD) and datetime (YYYY-MM-DD HH:MM:SS).
• Selection: Must use one of the allowed values (string), e.g., priority field with value "2".
• JSON/Properties: Accept nested objects directly.

---

5. Real-World Examples​

This section provides complete, ready-to-use JSON payload examples for common Odoo operations.

Example 1: Creating a CRM Lead​

Model: crm.lead
Operation: Create
{
"name": "Website Inquiry - John Doe",
"contact_name": "John Doe",
"email_from": "[email protected]",
"phone": "+1-555-0123",
"description": "Customer interested in Enterprise plan",
"type": "opportunity",
"priority": "2",
"user_id": 5,
"team_id": 3,
"tag_ids": [[6, 0, [1, 4, 7]]],
"expected_revenue": 15000.00,
"probability": 60.0,
"date_deadline": "2025-12-15"
}

Example 2: Creating a Helpdesk Ticket​

Model: helpdesk.ticket
Operation: Create
{
"name": "Unable to login to portal",
"partner_id": 123,
"team_id": 2,
"priority": "1",
"ticket_type_id": 5,
"description": "<p>Customer reports they cannot access their account after password reset.</p>",
"tag_ids": [[6, 0, [8, 12]]],
"sla_deadline": "2025-11-02 18:00:00"
}

Example 3: Updating a Sales Order​

Model: sale.order
Operation: Write (Update)
{
"state": "sale",
"commitment_date": "2025-11-15",
"order_line": [
[1, 45, {"product_uom_qty": 10}],
[0, 0, {
"product_id": 78,
"product_uom_qty": 5,
"price_unit": 150.00
}]
]
}

Example 4: Creating a Contact with Address​

Model: res.partner
Operation: Create
{
"name": "Acme Corporation",
"company_type": "company",
"email": "[email protected]",
"phone": "+1-555-9876",
"website": "https://acme.com",
"street": "123 Business Ave",
"city": "New York",
"state_id": 47,
"zip": "10001",
"country_id": 233,
"is_company": true,
"customer_rank": 1,
"category_id": [[6, 0, [2, 5]]]
}

Example 5: Creating an Invoice with Lines​

Model: account.move
Operation: Create
{
"move_type": "out_invoice",
"partner_id": 89,
"invoice_date": "2025-10-31",
"invoice_date_due": "2025-11-30",
"invoice_line_ids": [
[0, 0, {
"product_id": 34,
"quantity": 2,
"price_unit": 500.00,
"tax_ids": [[6, 0, [1]]]
}],
[0, 0, {
"product_id": 56,
"quantity": 1,
"price_unit": 1200.00,
"tax_ids": [[6, 0, [1]]]
}]
]
}

Example 6: Linking and Unlinking Many2many Records​

Model: project.task
Operation: Update tags
{
"tag_ids": [
[4, 10, 0],
[4, 15, 0],
[3, 8, 0]
]
}
Explanation: This links tags with IDs 10 and 15, and unlinks tag with ID 8.

---

Visual Reference​

[Image/Screenshot will be added here showing real API request/response examples]

---

6. Common Patterns & Tips​

Pattern 1: Replace All Related Records​

"tag_ids": [[6, 0, [1, 2, 3, 4]]]
This replaces all existing tags with the new list.

Pattern 2: Add Single Record to Many2many​

"tag_ids": [[4, 5, 0]]
This adds tag ID 5 without affecting existing tags.

Pattern 3: Create Child Records​

"order_line": [[0, 0, {"product_id": 10, "qty": 2}]]
This creates a new order line linked to the parent order.

Pattern 4: Update Existing Child Record​

"order_line": [[1, 25, {"qty": 5}]]
This updates the quantity of order line with ID 25.

---

This guide provides a complete reference for working with Odoo's JSON API across all standard field types and common use cases.