Bulk Transactions
Utility for sellers to bulk upload transactions.
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 15 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 |
| 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. |
| line_number | false | number | If this is an invoice with multiple lines, this line number will be used to uniquely identify individual lines of the invoice. Commenda will populate this value if it is not passed in. |
| price_per_unit | false | number >= 0 | Price per unit of the product sold on this line item. |
| quantity | false | number >= 0 | Number of units of product sold on this line item. |
| 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. |
| product_sku | false | string | A unique string used by the seller to identify the product being sold. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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 | 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 | true | 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 | true | 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. |
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.
Transaction Type Code
The type of transaction that occurred. Currently, SALE and REFUND are supported.
SALEtransactions will be used for nexus calculations and for filing.- By default, tax withheld on
REFUNDtransactions will be credited against futureSALEtransactions in the same jurisdiction. For any different tax treatment, please contact the Commenda team.
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.