Skip to main content

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.

​
Overview

Commenda uses tax transactions to calculate the seller’s tax obligations for filings and registration threshold tracking. If you are registered to pay taxes in a jurisdiction, the tax transactions will be automatically filed at the end of each filing period.

​
Key Concepts

​
Filing Status

Each tax transaction has a filing_status. Possible values:
  • UNCOMMITTED: A transaction is initially created with the status UNCOMMITTED. This indicates that the transaction has been created but has not yet been included in a filing. It remains open for updates or deletion.
  • IGNORED: An UNCOMMITTED transaction can be marked as IGNORED to exclude it from the filing process.
  • LOCKED: After the filing period concludes, all UNCOMMITTED transactions that have not been marked as IGNORED are eventually transitioned to LOCKED status. In this state, they cannot be updated or deleted. Transactions are filed after being moved to the LOCKED state.

​
Transaction id

  • The tax transaction id needs to be provided by the API user.
  • This allows for referential tracking and prevents deduplication in case the seller attempts to POST the same transaction twice.
  • The id does not need to be globally unique, but it must be unique for each seller.

​
Transaction Types

The system supports the following transaction types:
TypeDescriptionUse case
SALEStandard sales transactionNew sales, corrections, re-invoicing
REFUNDRefund of a previous saleFull or partial refunds of SALE transactions
RETURNLegacy return typeEquivalent to REFUND, maintained for backward compatibility
PURCHASEPurchase transactionRecording purchases for EU VAT / UK VAT input credit calculations
PURCHASE_REFUNDRefund of a previous purchaseAuto-derived when creating a refund against a PURCHASE transaction

​
Sales transactions

Use SALE for standard outgoing sales. You set transaction_type to SALE when creating the transaction.

​
Refund transactions

Use REFUND (or RETURN) for returns against a previous sale. Link the refund to the original sale via parent_invoice_id.

​
Purchase transactions

Use PURCHASE to record incoming purchase transactions. This is useful when you need to track input tax credits for EU VAT or UK VAT alongside your sales data.
Purchase transactions do not affect sales-focused flows like registration threshold tracking, filing calculations, or daily sales summaries. They are stored separately for input credit calculations.

​
Purchase refund transactions

PURCHASE_REFUND is automatically assigned when you create a refund against a PURCHASE transaction using the refund endpoint. You do not set this type directly — it is derived from the parent transaction’s type.

​
Amount sign rules

For SALE transactions
  • Line item amounts (price_per_unit * quantity) should normally be positive
  • Negative amounts are allowed for price corrections within an invoice (mixed with positive lines) or re-invoicing scenarios
For REFUND / RETURN transactions
  • Line item amounts (price_per_unit * quantity) must be negative
  • Can be achieved through either:
    • Negative quantity with positive price, OR
    • Positive quantity with negative price
  • All line items in a REFUND transaction must have negative amounts
For PURCHASE transactions
  • Line item amounts (price_per_unit * quantity) must be negative (similar to REFUND)
For PURCHASE_REFUND transactions
  • Line item amounts (price_per_unit * quantity) should be positive (similar to SALE)

​
Filtering by transaction type

When listing transactions, you can filter by type using the types query parameter (an array) or the legacy type parameter (a single value). If you do not provide a type filter, the API defaults to returning SALE, REFUND, and RETURN transactions only. PURCHASE and PURCHASE_REFUND transactions are excluded by default and must be explicitly requested. Priority order: types > type > default 
# Return only purchase transactions
GET /transactions?corporation_id=...&types=PURCHASE&types=PURCHASE_REFUND

# Return all transaction types
GET /transactions?corporation_id=...&types=SALE&types=REFUND&types=RETURN&types=PURCHASE&types=PURCHASE_REFUND

​
Tax remitter type

The tax_remitter_type field indicates which party is responsible for remitting tax on the transaction. This is relevant for marketplace transactions and international VAT scenarios.
ValueDescription
SELLERThe seller collects and remits tax (default)
MARKETPLACE_FACILITATORA marketplace facilitator collects and remits tax on behalf of the seller
BUYERThe buyer is responsible for remitting tax (reverse-charge mechanism, common in B2B VAT transactions)
When a transaction is marked with BUYER as the tax remitter type, it indicates a reverse-charge scenario where the buyer self-assesses and remits the tax. This is common in cross-border B2B transactions within VAT jurisdictions.

​
Bulk transactions

See Bulk Transactions.

​
Best practices

​
Transaction type selection

  • Use SALE for new sales and correction scenarios with mixed positive/negative lines
  • Use REFUND for refunds of previous sales
  • Use PURCHASE for incoming purchases where you need to track input tax credits
  • Ensure all REFUND and PURCHASE transaction line items have negative amounts
  • Do not set PURCHASE_REFUND directly — create a refund against a PURCHASE transaction instead

​
Amounts and signs

  • For re-invoicing corrections, use a SALE with mixed line signs
  • For refunds, use a REFUND with negative total line amounts
  • Be consistent within each transaction type

​
Reference original transactions

  • Always link REFUND transactions to their original sales via parent_invoice_id
  • When creating a refund against a PURCHASE, the system automatically assigns PURCHASE_REFUND as the type
  • For line-level refunds, match line_number with the original invoice

​
Date handling

  • Use transacted_at for the actual date of the return
  • Use reporting_date_override to control when the transaction appears in reports
  • Use calculation_date_override to apply historical tax rates from the original sale date