Skip to main content

​
Overview

Commenda uses tax transactions to calculate the seller’s tax obligations for filings and nexus tracking. In cases where sellers ave been selling in various US states prior to onboarding to Commenda, some retroactive analysis will be necessary for accurate nexus status 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.
Column HeaderRequiredFormatDescription
corporation_idtruestring (UUID)The ID of the corporation whose transactions are being uploaded
process_codetrueProcess CodeA code indicating the process being performed
transaction_typetrueTransaction TypeA code indicating the type of transaction (SALE or RETURN)
transaction_statusfalsestringStatus of the transaction. Valid values: UNCOMMITTED, COMMITTED, LOCKED, VOIDED
invoice_numbertruestringA unique ID for this invoice
transacted_attrueISO-8601 date stringThe date on which the transaction occurred, or the date on which tax liability should be recognized.
reporting_date_overridefalseISO-8601 date stringOptional date to control when the transaction appears in reports.
calculation_date_overridefalseISO-8601 date stringOptional date to use for tax rate lookups.
tax_date_overridefalseISO-8601 date stringOptional date to use for tax date override.
line_numberfalseintegerIf this is an invoice with multiple lines, this line number will be used to uniquely identify individual lines of the invoice. For RETURN transactions with line-level returns, this should match the line_number from the original invoice.
price_per_unittruenumberPrice per unit of the product sold on this line item. For RETURN transactions, this can be negative when used with positive quantity.
quantitytruenumberNumber of units of product sold/returned. For RETURN transactions, this can be negative when used with positive price_per_unit.
discountfalsenumber >= 0Discount applied to this line item. Handle invoice-level discounts by distributing them evenly across line items.
item_shippingfalsenumber >= 0Line-item-level shipping cost.
item_handlingfalsenumber >= 0Line-item-level handling cost.
item_taxfalsenumber >= 0Tax collected on this line item. Will be used for filing.
tax_includedtruebooleanWhether the pricing of this product is intended to be tax-inclusive.
product_idfalsestring (UUID)The ID of the sold product in Commenda’s platform. Cannot be used together with product_sku.
product_source_platform_idfalsestringThe unique ID for this product in the source platform.
product_skufalsestringA unique string used by the seller to identify the product being sold. Cannot be used together with product_id.
product_taxability_codefalseProduct Taxability CodeA code used to identify the type of product being sold, and whether the product is taxable in the destination jurisdiction. Defaults to TPP if not set.
customer_idfalsestring (UUID)The ID of the purchasing customer in Commenda’s platform.
customer_source_platform_idfalsestringThe unique ID for this customer in the source platform.
source_platformfalseSource PlatformA code indicating the integration via which the transaction entered Commenda’s system. This is not meant to indicate the platform on which the transaction took place. Must be provided together with source_platform_id.
source_platform_idfalsestringThe unique ID for this transaction or invoice in the source platform. This field should only be used for integrations. Must be provided together with source_platform.
exemption_reasonfalseExemption ReasonDuring import, this field can be used to indicate that the transaction is tax-exempt because the purchaser is exempt.
exemption_certificate_idfalsestring (UUID)ID in Commenda of the exemption certificate that’s linked to this transaction. Used to mark a transaction as exempt.
currency_codetrueISO-4217 currency stringCurrency in which the transaction took place.
exchange_ratefalsenumberExchange rate for the currency if different from the corporation’s base currency.
exchange_rate_effective_datefalseISO-8601 date stringDate when the exchange rate was effective.
parent_invoice_idfalsestringOptional (but recommended) for RETURN transactions. ID of the original sale transaction being returned.
ship_from_address_line_1falsestringAddress from which the shipment originated.
ship_from_address_line_2falsestringAddress from which the shipment originated.
ship_from_address_line_3falsestringAddress from which the shipment originated.
ship_from_cityfalsestringAddress from which the shipment originated.
ship_from_state_codefalseISO-3166-2 jurisdiction string valid in the origin countryAddress from which the shipment originated.
ship_from_zipfalsestring (Valid postal code in origin country)Address from which the shipment originated.
ship_from_country_codefalseISO-3166 Country StringAddress from which the shipment originated.
ship_to_address_line_1falsestringAddress to which the product is shipped or where the service is delivered.
ship_to_address_line_2falsestringAddress to which the product is shipped or where the service is delivered.
ship_to_address_line_3falsestringAddress to which the product is shipped or where the service is delivered.
ship_to_cityfalsestringAddress to which the product is shipped or where the service is delivered.
ship_to_state_codefalseISO-3166-2 jurisdiction string valid in the destination countryAddress to which the product is shipped or where the service is delivered.
ship_to_zipfalsestring (Valid postal code in destination country)Address to which the product is shipped or where the service is delivered.
ship_to_country_codetrueISO-3166 Country StringAddress to which the product is shipped or where the service is delivered.
marketplacefalsestringMarketplace name if the transaction is from a marketplace.
tax_remitter_typefalsestringType of tax remitter.
metadatafalsestring (JSON)Additional metadata for the transaction in JSON format.

​
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).

​
Special Rules for RETURN Transactions

When uploading RETURN transactions via CSV, the following rules apply:
  1. Required Fields:
    • transaction_type must be set to “RETURN”
    • parent_invoice_id is recommended but optional
  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

Error CodeDescriptionSolution
ERR_INVALID_RETURN_AMOUNTReturn line has positive amountEnsure price_per_unit * quantity < 0
ERR_INVALID_CORPORATION_IDCorporation ID doesn’t matchEnsure corporation_id matches the corporation specified in the upload
ERR_INVALID_INVOICE_IDMissing or invalid invoice_numberProvide a valid invoice_number for each row
ERR_INVALID_LINE_ITEM_COUNTToo many line items per invoiceReduce the number of line items per invoice

​
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: 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 nexus tracking or for filings. Currently the following options are supported: PURPOSE_RESALE, ENTITY_TYPE_NONPROFIT, GOVERNMENT, MANUFACTURER, AGRICULTURAL, OTHER.