Create Filings

Period Management

First, fetch available periods for your jurisdiction:

Endpoint: GET /api/tax-engine/v1/periods/

curl -X GET "https://api.abacus.com/api/tax-engine/v1/periods/?taxable_jurisdiction=DE" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "results": [
    {
      "id": "p1q2r3s4-t5u6-7890-vwx1-23456789abcd",
      "taxable_jurisdiction": "DE",
      "display_name": "Monthly VAT Return",
      "periodicity": "monthly",
      "day_of_month": 10,
      "months_to_add": 1,
      "ending_months": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
      "working_day_number": null,
      "is_ending_months_override_allowed": false,
      "is_day_of_month_override_allowed": false,
      "is_working_day_number_override_allowed": false,
      "filing_type_detail": {
        "name": "VAT Return",
        "code": "VAT100"
      }
    }
  ]
}

Understanding Period Objects

Period objects define the filing schedule and contain critical parameters that determine when filings are created:

Core Period Fields

Field	Type	Description	Example
`periodicity`	string	Filing frequency	`"monthly"`, `"quarterly"`, `"annually"`
`day_of_month`	integer	Due day of month (1-31)	`10`
`months_to_add`	integer	Months to add to period end for due date	`1`
`ending_months`	array	Months when periods end	`[1,2,3,4,5,6,7,8,9,10,11,12]`
`working_day_number`	integer/null	Nth working day of month (overrides day_of_month)	`5`

Period Examples

Monthly VAT (Germany):

{
  "periodicity": "monthly",
  "day_of_month": 10,
  "months_to_add": 1,
  "ending_months": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
  "working_day_number": null
}

Creates monthly filings due on the 10th of the following month

Quarterly VAT (UK):

{
  "periodicity": "quarterly",
  "day_of_month": 7,
  "months_to_add": 1,
  "ending_months": [3, 6, 9, 12],
  "working_day_number": null
}

Creates quarterly filings (Mar, Jun, Sep, Dec) due on the 7th of the following month

Monthly Extension (Italy):

{
  "periodicity": "monthly_extension",
  "day_of_month": 16,
  "months_to_add": 2,
  "ending_months": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
  "working_day_number": null
}

Creates monthly filings due on the 16th, two months after period end

Working Day Example (5th working day):

{
  "periodicity": "monthly",
  "day_of_month": 10,
  "months_to_add": 1,
  "ending_months": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12],
  "working_day_number": 5
}

Due on the 5th working day (Mon-Fri) of the month following period end

Seasonal Filing:

{
  "periodicity": "seasonal",
  "day_of_month": 31,
  "months_to_add": 1,
  "ending_months": [],
  "working_day_number": null
}

Single filing for a specific seasonal period

Available Periodicities

monthly - Every month
monthly_extension - Monthly with extended due dates
bi-monthly - Every two months
quarterly - Every three months (Mar, Jun, Sep, Dec)
quarterly_extension - Quarterly with extended due dates
annually - Once per year
semi-annually - Twice per year
tri-annually - Three times per year
annually_extension - Annual with extended due dates
seasonal - Custom seasonal period

Store period IDs mapped to jurisdiction and frequency in your metadata.

1. Create Registration Filing Type (RFT)

Endpoint: POST /api/registrations/v1/registration-filing-types/

curl -X POST https://api.abacus.com/api/registrations/v1/registration-filing-types/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "registration": "r1s2t3u4-v5w6-7890-xyz1-23456789abcd",
    "period": "p1q2r3s4-t5u6-7890-vwx1-23456789abcd",
    "date_of_filing_start": "2025-01-01"
  }'

Response:

{
  "id": "rft12345-6789-abcd-ef12-3456789abcde",
  "registration": "r1s2t3u4-v5w6-7890-xyz1-23456789abcd",
  "period": "p1q2r3s4-t5u6-7890-vwx1-23456789abcd",
  "entity_detail": {
    "id": "e1f2g3h4-i5j6-7890-klmn-op1234567890",
    "name": "EU Operations Ltd"
  },
  "taxable_jurisdiction_detail": {
    "id": "de-vat",
    "name": "Germany VAT"
  },
  "date_of_filing_start": "2025-01-01",
  "created_at": "2025-07-02T10:15:00Z"
}

How RFT Creation Triggers Filing Generation

When you create a Registration Filing Type (RFT), the system automatically generates future filings based on the period configuration. This process is handled by the FilingCreation service which:

Analyzes the period object to determine filing schedule
Calculates filing dates based on period parameters
Creates filing objects for each calculated period
Sets appropriate due dates considering working days and weekends

Filing Generation Logic

The system uses the following period fields to generate filings:

Period End Calculation:

Uses ending_months array to determine which months have period endings
For monthly periods: [1,2,3,4,5,6,7,8,9,10,11,12] (every month)
For quarterly periods: [3,6,9,12] (Mar, Jun, Sep, Dec)

Due Date Calculation:

Adds months_to_add to the period end date
Uses day_of_month or working_day_number for specific due day
Adjusts for weekends based on roll_weekend_days_to_next_working_day

Date Range:

Starts from date_of_filing_start (or registration date if earlier)
Generates filings up to a configurable future date (typically 2+ years)
Respects date_of_filing_end if specified

Example: Monthly VAT Filing Generation

Given this RFT with monthly period:

{
  "period": {
    "periodicity": "monthly",
    "day_of_month": 10,
    "months_to_add": 1,
    "ending_months": [1,2,3,4,5,6,7,8,9,10,11,12]
  },
  "date_of_filing_start": "2025-01-01"
}

Generated Filings:

January 2025 period (Jan 1-31) → Due Feb 10, 2025
February 2025 period (Feb 1-28) → Due Mar 10, 2025
March 2025 period (Mar 1-31) → Due Apr 10, 2025
...continues for ~2 years

Example: Quarterly VAT Filing Generation

Given this RFT with quarterly period:

{
  "period": {
    "periodicity": "quarterly", 
    "day_of_month": 7,
    "months_to_add": 1,
    "ending_months": [3,6,9,12]
  },
  "date_of_filing_start": "2025-01-01"
}

Generated Filings:

Q1 2025 period (Jan 1 - Mar 31) → Due Apr 7, 2025
Q2 2025 period (Apr 1 - Jun 30) → Due Jul 7, 2025
Q3 2025 period (Jul 1 - Sep 30) → Due Oct 7, 2025
Q4 2025 period (Oct 1 - Dec 31) → Due Jan 7, 2026

Working Day Adjustments

When working_day_number is specified, the system calculates the Nth working day (Monday-Friday) of the due month:

{
  "period": {
    "working_day_number": 5,
    "months_to_add": 1
  }
}

For a January period ending, due date would be the 5th working day of February.

Weekend Handling

The roll_weekend_days_to_next_working_day flag determines weekend adjustment:

true: Weekend due dates move to next Monday
false: Weekend due dates move to previous Friday

Filing Categories

Generated filings are categorized as:

STANDARD: Period ends after registration date (normal filings)
RETROSPECTIVE: Period ends before registration date (catch-up filings)

RFT Request Parameters

Parameter	Required	Description	Example
`registration`	Yes	Registration UUID	`"r1s2t3u4-v5w6-7890-xyz1-23456789abcd"`
`period`	Yes	Period UUID	`"p1q2r3s4-t5u6-7890-vwx1-23456789abcd"`
`date_of_filing_start`	No	When filings should start	`"2025-01-01"`
`date_of_filing_end`	No	When filings should end	`"2027-12-31"`
`day_of_month`	No	Override period's day_of_month	`15`
`working_day_number`	No	Override period's working_day_number	`3`
`ending_months`	No	Override period's ending_months	`[3,6,9,12]`

2. Manual Filing Creation (Optional)

Note: Filings are automatically created when you create an RFT. Manual filing creation is only needed for special cases like corrections, amendments, or custom periods.

Endpoint: POST /api/filing/v1/filings/

curl -X POST https://api.abacus.com/api/filing/v1/filings/ \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "registration_filing_type": "rft12345-6789-abcd-ef12-3456789abcde",
    "reporting_period_start": "2025-01-01",
    "reporting_period_end": "2025-01-31"
  }'

Response:

{
  "id": "f1i2l3i4-n5g6-7890-abcd-ef1234567890",
  "registration_filing_type": "rft12345-6789-abcd-ef12-3456789abcde",
  "reporting_period_start": "2025-01-01",
  "reporting_period_end": "2025-01-31",
  "status": "draft",
  "due_date": "2025-02-10",
  "created_at": "2025-07-02T10:20:00Z"
}

When to Use Manual Filing Creation

Corrections: Creating amended filings for previously submitted periods
Custom Periods: Non-standard reporting periods not covered by automatic generation
One-off Filings: Special circumstances requiring manual intervention
Testing: Creating test filings for development/validation purposes

Automatic vs Manual Filing Creation

Scenario	Method	When to Use
Standard Operations	Automatic (via RFT)	Regular recurring filings following period schedule
Corrections/Amendments	Manual	Fixing previously submitted filings
Custom Periods	Manual	Non-standard reporting periods
Retrospective Filings	Automatic (via RFT)	System handles catch-up filings automatically

3. View Generated Filings

After creating an RFT, you can view the automatically generated filings:

Endpoint: GET /api/filing/v1/filings/

curl -X GET "https://api.abacus.com/api/filing/v1/filings/?registration_filing_type=rft12345-6789-abcd-ef12-3456789abcde" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "count": 24,
  "results": [
    {
      "id": "f1i2l3i4-n5g6-7890-abcd-ef1234567890",
      "registration_filing_type": "rft12345-6789-abcd-ef12-3456789abcde",
      "period_start_date": "2025-01-01",
      "period_end_date": "2025-01-31", 
      "effective_due_date": "2025-02-10",
      "base_due_date": "2025-02-10",
      "status": "draft",
      "category": "standard",
      "created_at": "2025-07-02T10:15:30Z"
    },
    {
      "id": "f2i3l4i5-n6g7-8901-bcde-f23456789abc",
      "registration_filing_type": "rft12345-6789-abcd-ef12-3456789abcde", 
      "period_start_date": "2025-02-01",
      "period_end_date": "2025-02-28",
      "effective_due_date": "2025-03-10",
      "base_due_date": "2025-03-10", 
      "status": "draft",
      "category": "standard",
      "created_at": "2025-07-02T10:15:30Z"
    }
  ]
}

Filing Object Fields

Field	Description	Example
`period_start_date`	Start of reporting period	`"2025-01-01"`
`period_end_date`	End of reporting period	`"2025-01-31"`
`base_due_date`	Calculated due date before weekend adjustment	`"2025-02-10"`
`effective_due_date`	Final due date after weekend/holiday adjustment	`"2025-02-10"`
`category`	Filing category (`standard` or `retrospective`)	`"standard"`
`status`	Current filing status	`"draft"`

Filing Status Flow

draft → pending_approval → approved → submitted → accepted/rejected

Period Management​

Understanding Period Objects​

Core Period Fields​

Period Examples​

Available Periodicities​

1. Create Registration Filing Type (RFT)​

How RFT Creation Triggers Filing Generation​

Filing Generation Logic​

Example: Monthly VAT Filing Generation​

Example: Quarterly VAT Filing Generation​

Working Day Adjustments​

Weekend Handling​

Filing Categories​

RFT Request Parameters​

2. Manual Filing Creation (Optional)​

When to Use Manual Filing Creation​

Automatic vs Manual Filing Creation​

3. View Generated Filings​

Filing Object Fields​

Filing Status Flow​

Period Management

Understanding Period Objects

Core Period Fields

Period Examples

Available Periodicities

1. Create Registration Filing Type (RFT)

How RFT Creation Triggers Filing Generation

Filing Generation Logic

Example: Monthly VAT Filing Generation

Example: Quarterly VAT Filing Generation

Working Day Adjustments

Weekend Handling

Filing Categories

RFT Request Parameters

2. Manual Filing Creation (Optional)

When to Use Manual Filing Creation

Automatic vs Manual Filing Creation

3. View Generated Filings

Filing Object Fields

Filing Status Flow