Skip to main content
POST
/
api
/
v1
/
internal
/
filings
/
bulk
/
create
curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/internal/filings/bulk/create' \
  --header 'Authorization: Bearer <admin_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
    "registration_tax_type_id": "REG_STATE_CEN_06_RST",
    "tax_period_start_month": "2025-01",
    "tax_period_end_month": "2025-12"
  }'

{
  "created_filings": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
      "registration_tax_type_id": "REG_STATE_CEN_06_RST",
      "filing_content_id": "FC_US_06_RST",
      "jurisdiction_name": "California",
      "jurisdiction_type": "STATE_OR_PROVINCE",
      "form_title": "Sales and Use Tax Return",
      "filing_frequency": "QUARTERLY",
      "tax_period_start_date": "2025-01-01",
      "tax_period_end_date": "2025-03-31",
      "reporting_period_start_date": "2025-01-01",
      "reporting_period_end_date": "2025-03-31",
      "filing_due_date": "2025-04-30",
      "due_date": "2025-04-30",
      "status": "SCHEDULED",
      "created_at": 1706700000
    }
  ],
  "total_created": 4
}
Generate filing records for a registration and time period. The system creates filings based on the filing calendar content, with dates, frequencies, and form titles determined by the registration’s content configuration. This endpoint supports two input modes:
  • V2 — pass registration_tax_type_id to generate filings for a V2 registration
  • V1 — pass country, state, and filing_frequency for legacy registrations
Use the preview endpoint first to verify which filings will be created before calling this endpoint.

​
Request body

​
corporation_id
string
required
The corporation UUID.
​
registration_tax_type_id
string
The V2 registration content ID. When provided, the V2 filing path is used.Example: "REG_STATE_CEN_06_RST"
​
tax_period_start_month
string
required
The start of the tax period range in YYYY-MM format.Example: "2025-01"
​
tax_period_end_month
string
The end of the tax period range in YYYY-MM format. If omitted, only filings for the start month are generated.Example: "2025-12"
​
country
string
ISO country code. Required for V1 filings when registration_tax_type_id is not provided.
​
state
string
State or province code. Required for V1 filings when registration_tax_type_id is not provided.
​
filing_frequency
string
Filing frequency. Required for V1 filings when registration_tax_type_id is not provided.

​
Behavior

  • Duplicate protection — if a filing already exists for the same registration, filing content, frequency, and due date, it is not recreated. The uniqueness key for V2 filings is the combination of corporation_id, registration_tax_type_id, filing_content_id, filing_due_date, and filing_frequency. This allows parallel filing tracks under the same registration (e.g., a standard return and a Dauerfrist extension) to coexist. Existing filings that are not in SCHEDULED status are preserved.
  • Composite frequencies — if a registration has multiple frequencies (e.g., QUARTERLY and ANNUAL_RECONCILIATION), filings are generated for all matching calendar entries.
  • Ownership validation — the system verifies that the registration_tax_type_id belongs to the specified corporation.
curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/internal/filings/bulk/create' \
  --header 'Authorization: Bearer <admin_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
    "registration_tax_type_id": "REG_STATE_CEN_06_RST",
    "tax_period_start_month": "2025-01",
    "tax_period_end_month": "2025-12"
  }'

{
  "created_filings": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
      "registration_tax_type_id": "REG_STATE_CEN_06_RST",
      "filing_content_id": "FC_US_06_RST",
      "jurisdiction_name": "California",
      "jurisdiction_type": "STATE_OR_PROVINCE",
      "form_title": "Sales and Use Tax Return",
      "filing_frequency": "QUARTERLY",
      "tax_period_start_date": "2025-01-01",
      "tax_period_end_date": "2025-03-31",
      "reporting_period_start_date": "2025-01-01",
      "reporting_period_end_date": "2025-03-31",
      "filing_due_date": "2025-04-30",
      "due_date": "2025-04-30",
      "status": "SCHEDULED",
      "created_at": 1706700000
    }
  ],
  "total_created": 4
}