Tax Period Documentation

Overview

The Tax Period model (tax.period) defines tax reporting periods for organizing and filtering tax-related transactions. It provides a simple way to define date ranges for tax filing periods such as monthly, quarterly, or annual periods.

---

Model Information

Model Name: tax.period Display Name: Tax Period Key Fields: None (no unique constraint defined)

Features

• ❌ Audit logging enabled (_audit_log)
• ❌ Multi-company support (company_id)
• ❌ Full-text content search (_content_search)
• ✅ Simple date range definition
• ✅ Name-based search

---

Key Fields Reference

All Fields

Field	Type	Required	Description
name	Char	✅	Period name (searchable)
date_from	Date	❌	Period start date
date_to	Date	❌	Period end date

---

Default Ordering

Records are ordered by start date:

_order = "date_from"

---

API Methods

1. Create Tax Period

Method: create(vals, context)

Creates a new tax period.

Parameters:

vals = {
    "name": "Q1 2024",           # Required: Period name
    "date_from": "2024-01-01",   # Optional: Start date
    "date_to": "2024-03-31",     # Optional: End date
}

Returns: int - New record ID

Example:

period_id = get_model("tax.period").create({
    "name": "January 2024",
    "date_from": "2024-01-01",
    "date_to": "2024-01-31",
})

---

2. Search Tax Periods

Method: search(condition, context)

Search for tax periods.

Example:

# Find all periods
all_periods = get_model("tax.period").search([])

# Find period by name
period_ids = get_model("tax.period").search([["name", "=", "Q1 2024"]])

# Find periods for a year
period_ids = get_model("tax.period").search([
    ["date_from", ">=", "2024-01-01"],
    ["date_to", "<=", "2024-12-31"]
])

# Find period containing a specific date
period_ids = get_model("tax.period").search([
    ["date_from", "<=", "2024-06-15"],
    ["date_to", ">=", "2024-06-15"]
])

---

3. Browse Tax Periods

Method: browse(ids, context)

Retrieve tax period records.

Example:

periods = get_model("tax.period").browse(period_ids)
for period in periods:
    print(f"{period.name}: {period.date_from} to {period.date_to}")

---

4. Update Tax Period

Method: write(ids, vals, context)

Update tax period records.

Example:

get_model("tax.period").write([period_id], {
    "name": "Q1 2024 (Amended)",
})

---

5. Delete Tax Period

Method: delete(ids, context)

Delete tax period records.

Example:

get_model("tax.period").delete([period_id])

---

Common Use Cases

Use Case 1: Set Up Monthly Tax Periods

import calendar

year = 2024
for month in range(1, 13):
    last_day = calendar.monthrange(year, month)[1]
    month_name = calendar.month_name[month]

    get_model("tax.period").create({
        "name": f"{month_name} {year}",
        "date_from": f"{year}-{month:02d}-01",
        "date_to": f"{year}-{month:02d}-{last_day:02d}",
    })

---

Use Case 2: Set Up Quarterly Tax Periods

year = 2024
quarters = [
    ("Q1", "01-01", "03-31"),
    ("Q2", "04-01", "06-30"),
    ("Q3", "07-01", "09-30"),
    ("Q4", "10-01", "12-31"),
]

for q_name, start, end in quarters:
    get_model("tax.period").create({
        "name": f"{q_name} {year}",
        "date_from": f"{year}-{start}",
        "date_to": f"{year}-{end}",
    })

---

Use Case 3: Find Current Tax Period

import time

today = time.strftime("%Y-%m-%d")
period_ids = get_model("tax.period").search([
    ["date_from", "<=", today],
    ["date_to", ">=", today]
])

if period_ids:
    period = get_model("tax.period").browse(period_ids)[0]
    print(f"Current tax period: {period.name}")
else:
    print("No tax period defined for today")

---

Use Case 4: Generate Tax Report by Period

# Get tax transactions for a period
period = get_model("tax.period").browse([period_id])[0]

# Find move lines with tax in this period
tax_lines = get_model("account.move.line").search_browse([
    ["move_id.date", ">=", period.date_from],
    ["move_id.date", "<=", period.date_to],
    ["tax_comp_id", "!=", None],
    ["move_id.state", "=", "posted"]
])

# Summarize by tax component
tax_summary = {}
for line in tax_lines:
    comp_name = line.tax_comp_id.name
    tax_summary[comp_name] = tax_summary.get(comp_name, 0) + (line.credit - line.debit)

print(f"Tax Report for {period.name}")
print("-" * 40)
for comp, amount in tax_summary.items():
    print(f"  {comp}: {amount:,.2f}")

---

Use Case 5: Copy Periods to Next Year

# Copy 2024 periods to 2025
source_year = 2024
target_year = 2025

periods = get_model("tax.period").search_browse([
    ["date_from", ">=", f"{source_year}-01-01"],
    ["date_to", "<=", f"{source_year}-12-31"]
])

for period in periods:
    new_name = period.name.replace(str(source_year), str(target_year))
    new_from = period.date_from.replace(str(source_year), str(target_year))
    new_to = period.date_to.replace(str(source_year), str(target_year))

    get_model("tax.period").create({
        "name": new_name,
        "date_from": new_from,
        "date_to": new_to,
    })

---

Best Practices

1. Use Consistent Naming

# Good: Clear, consistent naming
periods = [
    {"name": "Jan 2024", ...},
    {"name": "Feb 2024", ...},
    {"name": "Mar 2024", ...},
]

# Or for quarters
periods = [
    {"name": "2024 Q1", ...},
    {"name": "2024 Q2", ...},
]

# Bad: Inconsistent naming
periods = [
    {"name": "January", ...},
    {"name": "2024-02", ...},
    {"name": "Q1", ...},
]

---

2. Avoid Overlapping Periods

# Good: Non-overlapping periods
period1 = {"date_from": "2024-01-01", "date_to": "2024-01-31"}
period2 = {"date_from": "2024-02-01", "date_to": "2024-02-29"}

# Bad: Overlapping periods (can cause confusion)
period1 = {"date_from": "2024-01-01", "date_to": "2024-02-15"}
period2 = {"date_from": "2024-02-01", "date_to": "2024-03-15"}

---

3. Set Up Periods in Advance

# Good: Create all periods for the year at once
# This ensures consistent reporting throughout the year

---

Troubleshooting

"No period found for date"

Cause: No tax period covers the specified date Solution: Create tax period covering the date range

"Multiple periods found"

Cause: Overlapping tax periods exist Solution: Review and fix overlapping date ranges

"Period ordering incorrect"

Cause: date_from not set on some periods Solution: Ensure all periods have date_from set

---

Testing Examples

Unit Test: Tax Period Creation

def test_tax_period():
    # Create period
    period_id = get_model("tax.period").create({
        "name": "Test Period",
        "date_from": "2024-01-01",
        "date_to": "2024-01-31",
    })

    # Verify
    period = get_model("tax.period").browse([period_id])[0]
    assert period.name == "Test Period"
    assert period.date_from == "2024-01-01"
    assert period.date_to == "2024-01-31"

    # Search by date
    found = get_model("tax.period").search([
        ["date_from", "<=", "2024-01-15"],
        ["date_to", ">=", "2024-01-15"]
    ])
    assert period_id in found

    # Cleanup
    get_model("tax.period").delete([period_id])

---

Security Considerations

Permission Model

• Typically managed by accounting/tax personnel
• Read access may be broader for reporting

Data Access

• Tax periods are shared across the system
• Changes affect all tax reporting

---

Integration Points

Tax periods can be used with: - Tax reports and summaries - VAT/GST filing - Tax invoice filtering - Regulatory compliance reports

---

Version History

Last Updated: December 2024 Model Version: tax_period.py Framework: Netforce

---

Additional Resources

• Tax Rate Documentation: account.tax.rate
• Tax Component Documentation: account.tax.component
• Journal Entry Documentation: account.move

---

This documentation is generated for developer onboarding and reference purposes.