The legacy Refund transaction interface is being replaced by the RETURN transaction type. While both are currently supported, new integrations should use RETURN transactions.

​
Overview

When a customer returns an item where sales tax was collected, a negative tax liability is generated, which can be credited against future sales in the same jurisdiction. The tax credit applied will match the actual tax amount collected and remitted from the original transaction, making it crucial to link the return to the original sale.

To link the return to the original transaction, pass the original transaction’s id as the parent_invoice_id.

Returns can be categorized as either:

  • FULL: The entire transaction amount is returned.
  • PARTIAL: Only specific items or amounts are returned. In this case, the line_item ids for all returned items must be provided.

Return transactions appear in the results from both the GET /transactions and GET /transactions/{id} endpoints, alongside ordinary sales transactions. They are identified by their transaction_type field as RETURN.

​
Amount Sign Rules

For all RETURN transactions, the line item amounts must be negative. This can be achieved in two ways:

  1. Negative quantity with positive price: Setting a negative value for quantity while keeping price_per_unit positive.
  2. Positive quantity with negative price: Setting a positive value for quantity while making price_per_unit negative.

The system validates that all line items in a RETURN transaction result in negative total amounts (price_per_unit * quantity < 0).

​
Common Validation Errors

Error CodeDescriptionSolution
ERR_INVALID_RETURN_AMOUNTReturn transaction has positive line amountEnsure all RETURN line items have negative total amounts
ERR_MISSING_PARENT_INVOICEReturn transaction missing parent invoice referenceAdd parent_invoice_id for RETURN transactions
ERR_MISSING_REFUND_TYPEReturn transaction missing refund typeSpecify refund_type as FULL or PARTIAL
ERR_INVALID_REFUND_QUANTITYRefund quantity exceeds original quantityEnsure refund quantity doesn’t exceed what was originally sold

​
Card Chargebacks

In the case of a card chargeback, you should wait until the dispute is resolved. If the dispute settles in favor of the buyer, create a return transaction to reflect the chargeback and Commenda will adjust the tax liability accordingly.