> ## Documentation Index > Fetch the complete documentation index at: https://docs.commenda.io/llms.txt > Use this file to discover all available pages before exploring further. # List filings > List a corporation's filings, newest first, with optional filters. Always pass `v2=true`. Use `filing_statuses` and the due-date filters to split upcoming returns from completed ones, for example `filing_statuses=FILED` for completed returns and `filing_statuses=SCHEDULED,ACCRUING,ACTIVE,OVERDUE` for open ones. ## OpenAPI ````yaml GET /filings openapi: 3.0.1 info: title: Commenda Public APIs description: >- APIs for Commenda entity management, indirect tax, compliance, and corporate operations. license: name: NONE url: NONE version: 1.0.0 servers: - url: https://api.prod.commenda.io/api/v1 description: Commenda platform APIs. - url: https://transaction-tax.api.in.commenda.io/api/v1 description: Global Indirect Tax API. security: - bearerAuth: [] paths: /filings: get: summary: List filings description: >- List a corporation's filings, newest first, with optional filters. Always pass `v2=true`. Use `filing_statuses` and the due-date filters to split upcoming returns from completed ones, for example `filing_statuses=FILED` for completed returns and `filing_statuses=SCHEDULED,ACCRUING,ACTIVE,OVERDUE` for open ones. operationId: listFilings parameters: - name: corporation_id in: query description: The unique identifier of the corporation whose filings to list. required: true schema: type: string format: uuid - name: v2 in: query description: >- Set to `true`. Required for the response and filters documented on this page. required: true schema: type: string enum: - 'true' - name: cursor in: query description: >- The `cursor` from the previous page. Omit it for the first page. When a response has no `cursor`, you have reached the last page. required: false schema: type: string - name: limit in: query description: Number of filings per page. required: false schema: type: integer minimum: 1 maximum: 100 default: 10 - name: filing_statuses in: query description: >- Comma-separated list of statuses to return. Allowed values: `SCHEDULED`, `ACCRUING`, `ACTIVE`, `FILED`, `OVERDUE`. An unknown value returns a `400`. required: false schema: type: string example: ACTIVE,OVERDUE - name: from_due_date in: query description: >- Returns only filings whose `filing_due_date` is on or after this date (`YYYY-MM-DD`). required: false schema: type: string format: date - name: to_due_date in: query description: >- Returns only filings whose `filing_due_date` is on or before this date (`YYYY-MM-DD`). required: false schema: type: string format: date - name: jurisdiction_ids in: query description: >- Comma-separated list of Commenda jurisdiction identifiers. Maximum 100 values. required: false schema: type: string example: STATE_CEN_06,COUNTRY_DE_3018 - name: filing_frequencies in: query description: >- Comma-separated list of filing frequencies (see `filing_frequency`). Maximum 100 values. An unknown value returns a `400`. required: false schema: type: string example: MONTHLY,QUARTERLY - name: registration_tax_type_id in: query description: Returns only filings for this registration tax type. required: false schema: type: string example: REG_STATE_CEN_06_RST - name: extend in: query description: >- Set to `filing_contribution` to include the EU/UK VAT box values on each filing as a `contributions` array. Any other value returns a `400`. required: false schema: type: string enum: - filing_contribution responses: '200': description: A page of filings content: application/json: schema: type: object properties: data: type: object properties: filings: type: array items: $ref: '#/components/schemas/Filing' total_filings: type: integer description: >- Total number of filings that match the filters, across all pages. cursor: type: string description: >- Pass this as `cursor` to get the next page. Not present on the last page. message: type: string example: Successfully fetched filings. '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Filing: type: object description: >- One tax return for one jurisdiction and one tax period. Money fields are decimals in major units of `reporting_currency` (for example, `1031.25` means 1,031.25). A money field is left out of the response when its value is zero or has not been recorded yet. properties: id: type: string format: uuid description: The unique identifier for the filing. corporation_id: type: string format: uuid description: The corporation this filing belongs to. form_title: type: string description: Name of the tax return form (e.g., "Sales and Use Tax Return"). description: type: string description: >- Additional details about the filing, such as the filing variant or deadline type. jurisdiction_id: type: string description: Commenda identifier of the jurisdiction the return is filed with. example: STATE_CEN_06 jurisdiction_name: type: string description: Human-readable jurisdiction name. example: California jurisdiction_type: type: string description: Type of jurisdiction the return is filed with. enum: - STATE_OR_PROVINCE - COUNTRY - TRADEBLOC - CITY_OR_COUNTY registration_tax_type_id: type: string description: >- Identifier of the registration tax type this filing belongs to. Can be used as a filter on List filings. example: REG_STATE_CEN_06_RST filing_frequency: $ref: '#/components/schemas/filing_frequency' tax_period_start_date: type: string format: date description: First day of the tax period the return covers. example: '2026-07-01' tax_period_end_date: type: string format: date description: Last day of the tax period the return covers. example: '2026-09-30' reporting_period_start_date: type: string format: date description: Start of the reporting period. May differ from the tax period. reporting_period_end_date: type: string format: date description: End of the reporting period. filing_due_date: type: string format: date description: Date by which the return must be filed. example: '2026-10-31' status: $ref: '#/components/schemas/Tax_filing_status' filed_at: type: string format: date description: >- Date the return was filed with the tax authority. Set once the filing is `FILED`. example: '2026-10-20' reporting_currency: type: string nullable: true description: ISO 4217 currency code that the money fields on this filing are in. example: USD estimated_taxable_amount: type: number description: >- Taxable sales computed by Commenda from the transactions in the period. Updated while the filing is open. example: 12500 estimated_non_taxable_amount: type: number description: Non-taxable sales computed from the transactions in the period. example: 1500.5 estimated_exempt_amount: type: number description: Exempt sales computed from the transactions in the period. example: 250 estimated_tax_collected: type: number description: Tax collected, computed from the transactions in the period. example: 1031.25 taxable_amount: type: number description: >- Taxable sales reported on the filed return. Recorded when the return is filed. example: 12480 non_taxable_amount: type: number description: Non-taxable sales reported on the filed return. example: 1500.5 exempt_amount: type: number description: Exempt sales reported on the filed return. example: 250 tax_liability: type: number description: Tax due on the filed return. example: 1029.6 tax_paid: type: number description: Amount paid to the tax authority for this return. example: 1029.6 penalty: type: number description: Penalty assessed on this return, if any. interest: type: number description: Interest assessed on this return, if any. filing_confirmation_number: type: string description: >- Confirmation number issued by the tax authority when the return was filed. example: 0012-3456-7890 payment_confirmation_number: type: string description: Confirmation number issued by the tax authority for the payment. example: PMT-998877 created_at: type: integer format: int64 description: When the filing was created, in Unix microseconds. example: 1751328000000000 contributions: type: array nullable: true description: >- Tax-return box values for EU and UK VAT filings. Only included on List filings when called with `extend=filing_contribution`; left out otherwise. An empty array means the box values have not been computed yet. items: $ref: '#/components/schemas/FilingContribution' Error: type: object required: - error properties: error: type: object properties: type: type: string description: 'Specific Error type. Example: CLIENT_INVALID_REQUEST_BODY.' example: CLIENT_INVALID_REQUEST_BODY doc_url: type: string description: >- A link to the docs with details about this error. Example: https://sales-tax-docs.commenda.io/ example: https://sales-tax-docs.commenda.io/ title: type: string description: >- A short title describing the error. Example: Missing query parameters. example: Failed to validate the request body detail: type: string description: >- A json string with a description on how to fix the error. Example {"description":"Please pass in a valid corporation_id"} status: type: number description: >- The status code. It should be the same as the HTTP protocol status code. Example: 200 example: 400 instance: type: string description: >- The relative path that was hit by the user. Example: /api/v1/corporations/1 Errors: type: array items: type: object properties: details: type: string description: More details on how to solve this particular error. pointer: type: string description: >- Relative reference to missing or invalid piece of passed information. filing_frequency: type: string enum: - MONTHLY - QUARTERLY - SEMI_ANNUALLY - ANNUAL_CALENDAR_YEAR - FISCAL_YEAR - MONTHLY_ACCELERATED_PREPAY_EARLY - QUARTERLY_PREPAY_MONTHLY - ANNUAL_RECONCILIATION - BI_MONTHLY - TRI_ANNUALLY - QUARTERLY_FEB - QUARTERLY_MAR description: >- How often the business is required to submit tax returns. V1 registrations typically use MONTHLY, QUARTERLY, SEMI_ANNUALLY, or ANNUAL_CALENDAR_YEAR. V2 registrations may use additional frequencies such as ANNUAL_RECONCILIATION (for jurisdictions requiring a separate annual reconciliation filing alongside periodic returns) or region-specific variants like QUARTERLY_FEB and QUARTERLY_MAR. Tax_filing_status: type: string enum: - SCHEDULED - ACCRUING - ACTIVE - FILED - OVERDUE description: >- Current status of the filing. SCHEDULED means the filing has been created but the tax period has not yet started. ACCRUING means transactions are being collected for this period. ACTIVE means the filing is ready for review and submission. FILED means the return has been submitted. OVERDUE means the due date has passed without filing. FilingContribution: type: object properties: id: type: string format: uuid description: Unique identifier for this contribution. example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 filing_id: type: string format: uuid description: The filing this contribution belongs to. example: f1e2d3c4-b5a6-7890-abcd-ef1234567890 filing_contribution_id: type: string description: >- Stable content identifier that links this contribution to its tax return box rule definition. example: REG_COUNTRY_DE_3018_VAT_01_01 filing_through_jurisdiction: type: string nullable: true description: >- Commenda jurisdiction identifier for the member state this contribution applies to. Present for multi-jurisdiction filings (e.g., EU OSS/IOSS); null for single-jurisdiction filings. example: COUNTRY_DE_3018 value: type: integer format: int64 description: >- The computed monetary amount in minor currency units (e.g., cents). For example, a value of 12345 represents 123.45 in the filing currency. example: 12345 value_type: type: string description: The type of the value field. Currently always `INTEGER`. example: INTEGER box_id: type: string description: Identifier for the tax return form box this contribution maps to. example: DE_81 box_name: type: string description: Human-readable name of the tax return form box. example: Steuerpflichtige Umsätze box_order: type: integer format: int32 description: Display order of the box on the tax return form. example: 1 box_type: type: string description: Classification of the box (e.g., input, output, total). example: OUTPUT created_at: type: integer format: int64 description: Timestamp when this contribution was created, in Unix microseconds. example: 1713168000000000 updated_at: type: integer format: int64 description: >- Timestamp when this contribution was last updated, in Unix microseconds. example: 1713168000000000 securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.