Approve a filing
Approve a filing, moving it into the FILING lifecycle and locking its transactions. Requires an ADMIN or OWNER credential; send an Organization-Id, Connection-Id or Entity-Id selector to say which organization it belongs to. Approving a BACK_FILING with published terms requires backFilingTermsId. Pass autoFile: true to also turn on the organization's auto-file setting as part of the approval (applied only after it succeeds); omit it to leave the setting unchanged.
Approving a filing that is not UNFILED or PAUSED is a no-op and returns the filing unchanged. Returns 404 if the filing does not exist or belongs to an organization your credential cannot access, 403 if its jurisdiction is not enabled, 403 PLAN_UPGRADE_REQUIRED when the organization is on a free plan, 403 FORBIDDEN when the organization's plan does not include managed filings, and 409 if a filing already exists for the period.
Authorization
Headers
Release date, as YYYY-MM-DD. Defaults to 2026-07-21.
Target organization id (Organization-Id selector).
Target connection id; resolves to its organization.
Platform entity id; resolves to a connection's organization.
Optional source to disambiguate an Entity-Id.
Path parameters
The unique identifier of the filing.
Body
Id of the back-filing terms version the customer accepted, if any.
When the customer accepted the back-filing terms (advisory).
Client-minted id for this confirm attempt, stored on the audit row so a double-submit or retry of one gesture can be collapsed by readers.
When true, also turn on the organization's auto-file setting as part of the approval, so future returns file automatically. Applied only after the approval succeeds; omit, null or false leaves the setting unchanged. No effect for organizations on the new auto-filing experience.
Response
Kintsugi's unique identifier for the filing.
Organization the filing belongs to.
Display name of the organization the filing belongs to. null when the organization has no name set.
The registration this filing period is filed under, if any.
Lifecycle status of the filing.
UNFILEDFILEDFILINGPAUSEDSKIPPEDCANCELLEDISSUEThe kind of filing period: REGULAR, AMENDMENT or BACK_FILING (a legacy PREPAYMENT value may appear on historical rows).
Which taxes this filing covers, from the associated registration.
SALES_TAXUSE_TAXSALES_AND_USE_TAXRETAIL_DELIVERY_FEEISO 3166-1 alpha-2 country code of the filing jurisdiction.
State or province code, or '' for a country-level filing.
Human-readable jurisdiction name.
First day of the filing period, as YYYY-MM-DD.
Last day of the filing period, as YYYY-MM-DD.
When the return is due, as YYYY-MM-DD.
When the return was filed, as YYYY-MM-DD; null until filed.
Return confirmation id from the jurisdiction portal; null until filed.
Payment confirmation id from the jurisdiction portal; null until paid.
Date a paused filing auto-resumes, as YYYY-MM-DD; null when not paused.
Whether this filing is structurally eligible to be paused: it is not a back-filing, it is in a pauseable status, and its organization is on the auto-filing experience. The time-of-month pause window is not included; derive that client-side from dueDate.
Whether this filing can be approved. false when approval is blocked (for example by unapproved products or addresses), which disables the per-row Approve and file actions.
Why the filing was skipped, if it was; null otherwise.
Whether this period is a prepayment rather than a full return.
Whether this is the registration's final filing period.
Whether this is a state Retail Delivery Fee return, a separate filing from the state's sales tax return.
Number of transactions in the filing period.
The jurisdiction's filing portal URL, if known.
When the filing was approved, as an RFC-3339 UTC timestamp; null if not.
When the filing was created, as an RFC-3339 UTC timestamp.
ISO-4217 currency every amount on this filing is in; null until the filing's amounts settle.
Net amount due for the filing.
Calculated tax for the period.
Manual adjustment applied to the amount due.
Vendor/timely-filing discounts applied.
Fees added to the amount due.
Whether amountFees is a penalty, interest, or other fee. Null when the fee was recorded before the label existed.
PENALTYINTERESTOTHERPenalties added to the amount due.
Tax collected on transactions in the period.
Use tax owed for the period.
Gross sales in the period.
Total tax liability for the filing.
Tax remitted to the jurisdiction; 0 until filed.
Input VAT this filing claimed, subtracted from liability; 0 outside EU/UK VAT filings.
Prior-year input VAT pro-rata true-up on this filing; 0 until posted and outside EU/UK VAT filings.
Filing frequency from the associated registration.
UNKNOWNMONTHLYQUARTERLYSEMI_ANNUALLYANNUALLYANNUAL_FISCAL_YEARSEMI_MONTHLYBI_MONTHLYFOUR_MONTHLYQUARTERLY_PREPAYMENTOSS scheme (UNION/NON_UNION/IOSS) from the registration, if any.
UNIONNON_UNIONIOSSDisplay-only balance-due breakdown for CA Quarterly Prepayment reconciliation filings. When present, show balanceDue instead of totalTaxLiability. Absent means show totalTaxLiability as usual.
Display-only CDTFA Option 2 (135% of May liability) for CA Quarterly Prepayment May prepayment filings. Absent means show totalTaxLiability.
Display-only estimated penalties and interest for BACK_FILING rows. Null means unknown; zero is a genuine not-yet-late or zero-tax outcome.
Customer-facing P&I timing tag for BACK_FILING rows, e.g. 'Paid with return' or 'State bills you later'.
Sales composition for the period (taxable, exempt, marketplace count, credits utilized, deferred count). Absent unless the request passes expand=salesBreakdown.
EU/UK input-VAT recovery rate pair for the filing. Absent unless the request passes expand=vatRecovery.
The filing's return/payment/additional artifacts resolved by slot, each downloadable through the attachments API. Absent unless the request passes expand=artifacts.
Successful Response
The request was invalid.
Authentication failed or was missing.
The credential is not permitted for this request.
The requested resource was not found.
The request conflicts with existing state.
The request failed validation.