Skip to main content

​
Overview

Commenda uses tax transactions to calculate the seller’s tax obligations for filings and registration threshold tracking. In cases where sellers have been selling in various US states prior to onboarding to Commenda, some retroactive analysis will be necessary for accurate registration threshold evaluation.

​
Usage

Files will be uploaded through a POST to the transactions/bulk endpoint. They must be exactly the correct format, and are limited to 50 MB.

​
Error Handling

Default behavior is to load valid rows, and return an array detailing which rows were unable to be loaded, with the error associated with the row.

​
CSV Format

Files must be uploaded in CSV format, with the headers specified in our bulk uploads template.

​
Transaction Type Code

One of the following values:
  • SALE: Standard sales transaction. Normally contains positive amounts but can include negative amounts for corrections.
  • RETURN: Return/refund transaction. All line items must have negative total amounts (price_per_unit * quantity < 0).
  • PURCHASE: Purchase transaction for input tax credit tracking (e.g. EU VAT, UK VAT). All line items must have negative total amounts.
  • PURCHASE_REFUND: Refund of a purchase transaction. Auto-derived when creating a refund against a PURCHASE — do not set directly in bulk uploads.

​
Special rules for RETURN and PURCHASE transactions

When uploading RETURN or PURCHASE transactions via CSV, the following rules apply:
  1. Required fields:
    • transaction_type must be set to “RETURN” or “PURCHASE”
    • parent_invoice_id is recommended but optional for RETURN transactions
  2. Amount sign rules:
    • All line items must have negative total amounts
    • This can be achieved by either:
      • Setting negative quantity with positive price_per_unit, OR
      • Setting positive quantity with negative price_per_unit
  3. Line number matching:
    • For line-level returns, the line_number should match the original invoice’s line number

​
Common Validation Errors in Bulk Upload

​
Process Code

Indicates which operation is being performed (create transaction, update transaction, calculate tax, etc). Currently only transaction create is supported. Currently only INSERT_TRANSACTION is supported.

​
Source Platform

The method by which the transaction entered Commenda’s system. Currently the following options are supported: BIGCOMMERCE, BUSY, HUBSPOT, MEKARI_JURNAL, MS_DYNAMICS_365, MYOB_BUSINESS, NETSUITE, ODOO_ACCOUNTING, PAYPAL, PIPEDRIVE, QOYOD, QUICKBOOKS, QUICKBOOKS_SANDBOX, RAZORPAY, ROOTFI_SANDBOX, SAGE_CLOUD_ACCOUNTING, SAGE_ZA_CLOUD_ACCOUNTING, SHOPIFY, STRIPE, TALLY, WAFEQ, WAVE, WOOCOMMERCE, XERO, ZOHO_BOOKS, ZOHO_CRM.

​
Exemption Reason

Reason why a purchaser is exempt from sales tax. Used to manually specify that a transaction is exempt because its purchaser is exempt. When this field is set, the transaction will not be considered for registration threshold tracking or for filings. Currently the following options are supported: PURPOSE_RESALE, ENTITY_TYPE_NONPROFIT, GOVERNMENT, MANUFACTURER, AGRICULTURAL, EXEMPT_PRODUCT, OTHER.

​
Tax Remitter Type

Indicates which party is responsible for remitting the tax on the transaction. This field is relevant for VAT and reverse-charge scenarios. Currently the following options are supported:
  • SELLER: The seller is responsible for collecting and remitting tax (default behavior).
  • MARKETPLACE_FACILITATOR: A marketplace facilitator collects and remits the tax on behalf of the seller.
  • BUYER: The buyer is responsible for remitting the tax (reverse-charge mechanism, common in B2B VAT transactions).