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 (SALE or RETURN) |
| 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. |
| line_number | false | string | 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. |
| 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. |
| 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 (UUID) | Optional (but recommended) for RETURN transactions. ID of the original sale transaction being returned. |
| refund_type | false | string (FULL or PARTIAL) | Required for RETURN transactions. Indicates whether this is a full or partial return. |
| 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. |
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:
-
Required Fields:
transaction_typemust be set to “RETURN”parent_invoice_idmust reference the original salerefund_typemust be specified as “FULL” or “PARTIAL”
-
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_MISSING_PARENT_INVOICE | Missing parent invoice reference | Add parent_invoice_id for RETURN rows |
| ERR_MISSING_REFUND_TYPE | Missing refund type | Add refund_type as FULL or PARTIAL |
| ERR_INVALID_REFUND_QUANTITY | Refund quantity exceeds original | Check quantity against original 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.
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 (SALE or RETURN) |
| 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. |
| line_number | false | string | 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. |
| 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. |
| 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 (UUID) | Optional (but recommended) for RETURN transactions. ID of the original sale transaction being returned. |
| refund_type | false | string (FULL or PARTIAL) | Required for RETURN transactions. Indicates whether this is a full or partial return. |
| 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. |
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:
-
Required Fields:
transaction_typemust be set to “RETURN”parent_invoice_idmust reference the original salerefund_typemust be specified as “FULL” or “PARTIAL”
-
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_MISSING_PARENT_INVOICE | Missing parent invoice reference | Add parent_invoice_id for RETURN rows |
| ERR_MISSING_REFUND_TYPE | Missing refund type | Add refund_type as FULL or PARTIAL |
| ERR_INVALID_REFUND_QUANTITY | Refund quantity exceeds original | Check quantity against original 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.