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_item
ids 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
quantity
while keepingprice_per_unit
positive. - Positive quantity with negative price: Setting a positive value for
quantity
while makingprice_per_unit
negative.
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 |