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. 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 aPOST 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 Header | Required | Format | Description |
|---|---|---|---|
| corporation_id | true | string (UUID) | The ID of the corporation whose transactions are being uploaded |
| process_code | true | Process Code | A code indicating the process being performed |
| transaction_type | true | Transaction Type | A code indicating the type of transaction (SALE, RETURN, or PURCHASE) |
| transaction_status | false | string | Status of the transaction. Valid values: UNCOMMITTED, COMMITTED, LOCKED, VOIDED |
| invoice_number | true | string | A unique ID for this invoice |
| transacted_at | true | ISO-8601 date string | The date on which the transaction occurred, or the date on which tax liability should be recognized. |
| reporting_date_override | false | ISO-8601 date string | Optional date to control when the transaction appears in reports. |
| calculation_date_override | false | ISO-8601 date string | Optional date to use for tax rate lookups. |
| tax_date_override | false | ISO-8601 date string | Optional date to use for tax date override. |
| line_number | false | integer | If 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_unit | true | number | Price per unit of the product sold on this line item. For RETURN transactions, this can be negative when used with positive quantity. |
| quantity | true | number | Number of units of product sold/returned. For RETURN transactions, this can be negative when used with positive price_per_unit. |
| discount | false | number >= 0 | Discount applied to this line item. Handle invoice-level discounts by distributing them evenly across line items. |
| item_shipping | false | number >= 0 | Line-item-level shipping cost. |
| item_handling | false | number >= 0 | Line-item-level handling cost. |
| item_tax | false | number >= 0 | Tax collected on this line item. Will be used for filing. |
| tax_included | true | boolean | Whether the pricing of this product is intended to be tax-inclusive. |
| product_id | false | string (UUID) | The ID of the sold product in Commenda’s platform. Cannot be used together with product_sku. |
| product_source_platform_id | false | string | The unique ID for this product in the source platform. |
| product_sku | false | string | A unique string used by the seller to identify the product being sold. Cannot be used together with product_id. |
| product_taxability_code | false | Product Taxability Code | A 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_id | false | string (UUID) | The ID of the purchasing customer in Commenda’s platform. |
| customer_source_platform_id | false | string | The unique ID for this customer in the source platform. |
| source_platform | false | Source Platform | A 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_id | false | string | The 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_reason | false | Exemption Reason | During import, this field can be used to indicate that the transaction is tax-exempt because the purchaser is exempt. |
| exemption_certificate_id | false | string (UUID) | ID in Commenda of the exemption certificate that’s linked to this transaction. Used to mark a transaction as exempt. |
| currency_code | true | ISO-4217 currency string | Currency in which the transaction took place. |
| exchange_rate | false | number | Exchange rate for the currency if different from the corporation’s base currency. |
| exchange_rate_effective_date | false | ISO-8601 date string | Date when the exchange rate was effective. |
| parent_invoice_id | false | string | Optional (but recommended) for RETURN transactions. ID of the original sale transaction being returned. |
| ship_from_address_line_1 | false | string | Address from which the shipment originated. |
| ship_from_address_line_2 | false | string | Address from which the shipment originated. |
| ship_from_address_line_3 | false | string | Address from which the shipment originated. |
| ship_from_city | false | string | Address from which the shipment originated. |
| ship_from_state_code | false | ISO-3166-2 jurisdiction string valid in the origin country | Address from which the shipment originated. |
| ship_from_zip | false | string (Valid postal code in origin country) | Address from which the shipment originated. |
| ship_from_country_code | false | ISO-3166 Country String | Address from which the shipment originated. |
| ship_to_address_line_1 | false | string | Address to which the product is shipped or where the service is delivered. |
| ship_to_address_line_2 https://github.com/commenda-eng/product-and-api-docs/pull/73/conflict?name=engine%252Findirect-tax%252Ftransaction%252Fbulk-transactions.mdx&ancestor_oid=b4294b63c40ee5f14238c5993819b25b427f88a1&base_oid=e54b06895cc2f8a15d40e39ac3f42cd2882df35f&head_oid=d4fe0fc5a78c1f2ae643056bc6a64eb21bd5afb6 | false | string | Address to which the product is shipped or where the service is delivered. |
| ship_to_address_line_3 | false | string | Address to which the product is shipped or where the service is delivered. |
| ship_to_city | false | string | Address to which the product is shipped or where the service is delivered. |
| ship_to_state_code | false | ISO-3166-2 jurisdiction string valid in the destination country | Address to which the product is shipped or where the service is delivered. |
| ship_to_zip | false | string (Valid postal code in destination country) | Address to which the product is shipped or where the service is delivered. |
| ship_to_country_code | true | ISO-3166 Country String | Address to which the product is shipped or where the service is delivered. |
| customer_business_identification_number | false | string | The customer’s tax or business registration number (e.g., VAT ID, EIN, GST number). Automatically populated when syncing from integrations that provide this data. |
| marketplace | false | string | Marketplace name if the transaction is from a marketplace. |
| tax_remitter_type | false | Tax Remitter Type | Indicates which party is responsible for remitting tax on the transaction. |
| metadata | false | string (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).
- 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:-
Required fields:
transaction_typemust be set to “RETURN” or “PURCHASE”parent_invoice_idis recommended but optional for RETURN transactions
-
Amount sign rules:
- All line items must have negative total amounts
- This can be achieved by either:
- Setting negative
quantitywith positiveprice_per_unit, OR - Setting positive
quantitywith negativeprice_per_unit
- Setting negative
-
Line number matching:
- For line-level returns, the
line_numbershould match the original invoice’s line number
- For line-level returns, the
Common Validation Errors in Bulk Upload
| Error Code | Description | Solution |
|---|---|---|
| ERR_INVALID_RETURN_AMOUNT | Return line has positive amount | Ensure price_per_unit * quantity < 0 |
| ERR_INVALID_CORPORATION_ID | Corporation ID doesn’t match | Ensure corporation_id matches the corporation specified in the upload |
| ERR_INVALID_INVOICE_ID | Missing or invalid invoice_number | Provide a valid invoice_number for each row |
| ERR_INVALID_LINE_ITEM_COUNT | Too many line items per invoice | Reduce 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 onlyINSERT_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).