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’sid 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_itemids for all returned items must be provided.
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:- Negative quantity with positive price: Setting a negative value for
quantitywhile keepingprice_per_unitpositive. - Positive quantity with negative price: Setting a positive value for
quantitywhile makingprice_per_unitnegative.
price_per_unit * quantity < 0).
Common Validation Errors
| Error Code | Description | Solution |
|---|---|---|
| ERR_INVALID_RETURN_AMOUNT | Return transaction has positive line amount | Ensure all RETURN line items have negative total amounts |
| ERR_MISSING_PARENT_INVOICE | Return transaction missing parent invoice reference | Add parent_invoice_id for RETURN transactions |
| ERR_MISSING_REFUND_TYPE | Return transaction missing refund type | Specify refund_type as FULL or PARTIAL |
| ERR_INVALID_REFUND_QUANTITY | Refund quantity exceeds original quantity | Ensure refund quantity doesn’t exceed what was originally sold |