Skip to main content
POST
/
api
/
v1
/
internal
/
filings
/
preview
curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/internal/filings/preview' \
  --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-06"
  }'

{
  "proposed_filings": [
    {
      "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
      "registration_tax_type_id": "REG_STATE_CEN_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"
    },
    {
      "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
      "registration_tax_type_id": "REG_STATE_CEN_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-04-01",
      "tax_period_end_date": "2025-06-30",
      "reporting_period_start_date": "2025-04-01",
      "reporting_period_end_date": "2025-06-30",
      "filing_due_date": "2025-07-31",
      "due_date": "2025-07-31",
      "status": "SCHEDULED"
    }
  ]
}
Preview the filings that would be generated for a given registration and time period. This is a read-only operation — no filings are created. Use this to verify the filing schedule before committing. The preview endpoint supports two input modes:
  • V2 — pass registration_tax_type_id to preview filings for a V2 registration
  • V1 — pass country, state, and filing_frequency for legacy registrations

​
Request body

​
corporation_id
string
required
The corporation UUID.
​
registration_tax_type_id
string
The V2 registration content ID. When provided, the V2 filing calendar 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 returned.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.

​
How V2 preview works

When you provide a registration_tax_type_id, the system:
  1. Validates that the registration belongs to the specified corporation
  2. Looks up all filing calendar entries for that registration_tax_type_id
  3. Filters entries to those whose tax period falls within the requested date range
  4. Expands composite frequencies — if a registration has multiple frequencies (e.g., QUARTERLY and ANNUAL_RECONCILIATION), all matching entries are included
  5. Returns the proposed filings with dates, frequencies, and form titles
curl --request POST \
  --url 'https://transaction-tax.api.in.commenda.io/api/v1/internal/filings/preview' \
  --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-06"
  }'

{
  "proposed_filings": [
    {
      "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
      "registration_tax_type_id": "REG_STATE_CEN_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"
    },
    {
      "corporation_id": "550e8400-e29b-41d4-a716-446655440000",
      "registration_tax_type_id": "REG_STATE_CEN_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-04-01",
      "tax_period_end_date": "2025-06-30",
      "reporting_period_start_date": "2025-04-01",
      "reporting_period_end_date": "2025-06-30",
      "filing_due_date": "2025-07-31",
      "due_date": "2025-07-31",
      "status": "SCHEDULED"
    }
  ]
}