DEV-6903 Resolve partial refund issue

[azane-code]

Root cause:
For tax-only (or other non-product) refunds in Magento, the credit memo often contains no product line items (qty = 0) and no shipping. Our integration was still calling TaxCloud’s Returned API with an empty cartItems list. TaxCloud interprets a Returned call with no items as a full order return, which is why orders like 18871 were being marked as fully returned instead of partially refunded (tax-only).

Fix implemented:

We now only include product items with qty > 0 when building cartItems.

Added a safeguard to prevent division by zero when calculating per-unit discounts.

If there are no product or shipping items to return, we skip calling the Returned API entirely and return success so Magento does not treat the credit memo as failed.

New behavior:
Tax-only refunds will no longer trigger a Returned call, so TaxCloud will not mark the order as fully returned.

Note: This fix applies going forward. Existing incorrect records (e.g. 18871 / WEB1456336) would need to be corrected directly in TaxCloud if historical accuracy is required.

[GusOhnesorge]

Okay so just to make sure I understand

• Magento has a way to create a return for just tax (to refund the customer the tax)
• This triggers an event that has no line items to create a return
• We of course see an empty return and say "that's a full return"
• Presumably these are situations where the customer should have been tax exempt, but accidentally got charged tax for whatever reason?

Questions:

• Was there anything else we could use in the payload to generate a return? Some amount being returned or something?
• Shouldn't this change how much tax we need to file for the merchant?
• If we just skip calling our api with this update, don't we end up with data that doesn't reflect reality and we end up collecting extra tax from the merchant?

[azane-code]

Okay so just to make sure I understand

• Magento has a way to create a return for just tax (to refund the customer the tax)
• This triggers an event that has no line items to create a return
• We of course see an empty return and say "that's a full return"
• Presumably these are situations where the customer should have been tax exempt, but accidentally got charged tax for whatever reason?

Questions:

• Was there anything else we could use in the payload to generate a return? Some amount being returned or something?
• Shouldn't this change how much tax we need to file for the merchant?
• If we just skip calling our api with this update, don't we end up with data that doesn't reflect reality and we end up collecting extra tax from the merchant?

1. Anything else in the payload we could use for a return?
We have amounts (e.g. $creditmemo->getTaxAmount()), but the Returned API only takes item-based cartItems (ItemID, TIC, Price, Qty, Tax). There’s no “refund $X of tax” parameter. Whether a synthetic “tax-adjustment” item or ReturnedPro is supported would need confirmation.

2. Shouldn’t this change how much tax we file for the merchant?
Yes. A tax-only refund should reduce what the merchant remits; that’s why we’d want to report it if the API allows it.

3. If we skip the API call, don’t we end up with wrong data and over-collecting from the merchant?
Yes. Skipping avoids the bug (treating tax-only as full return) but doesn’t report the tax refund, so TaxCloud’s data can be high and we could over-collect.