Zoho Books API v3: Listing Refunds for a Contact

The List Refunds API allows you to retrieve a history of all payment refunds issued to a specific customer or received from a vendor. This endpoint provides granular details on refund dates, amounts, and the original payment references, making it an essential tool for building financial dashboards and automated reconciliation engines.

At Kalki LLP, we implement this endpoint for clients who need to sync "Return & Refund" data from their E-commerce platforms (like Shopify or Magento) directly into Zoho Books.

1. The Listing Request (GET)

To fetch the refund history for a specific contact, perform a GET request targeting the contact's unique ID.

Endpoint: GET /contacts/{contact_id}/refunds?organization_id={organization_id}

Mandatory Headers

2. API Response Structure

The response returns a refunds array. Each object details the refund amount, the payment it originated from, and the current status of the refund.

Sample JSON Response:

{
    "code": 0,
    "message": "success",
    "refunds": [
        {
            "refund_id": "460000000026201",
            "contact_id": "460000000026049",
            "customer_name": "Kalki LLP Solutions",
            "date": "2023-11-10",
            "refund_mode": "bank_transfer",
            "reference_number": "REF-99882",
            "amount": 150.00,
            "status": "refunded",
            "description": "Refund for damaged goods return."
        }
    ]
}

3. Implementation in Deluge (Kalki LLP Audit Script)

This script is used to calculate the total amount refunded to a customer over their lifetime.

// Target IDs
contactID = "460000000026049";
orgID = "123456789";

// Execute the GET request
response = invokeurl
[
	url :"https://www.zohoapis.in/books/v3/contacts/" + contactID + "/refunds?organization_id=" + orgID
	type :GET
	connection :"kalki_books_connection"
];

if(response.get("code") == 0)
{
    refundsList = response.get("refunds");
    totalRefunded = 0.0;
    
    for each refund in refundsList
    {
        totalRefunded = totalRefunded + refund.get("amount").toDecimal();
    }
    info "Kalki Report: Total Refunded to Customer: " + totalRefunded;
}
else
{
    info "Kalki Error: Could not fetch refunds. " + response.get("message");
}

4. Error Logs & Troubleshooting

5. Strategic Advantage: Why Track Refunds?

For kalkillp.com clients, retrieving refund data programmatically provides:

1. Net Revenue Calculation: Automating the subtraction of refunds from gross sales to find the true "Lifetime Value" (LTV) of a customer.

2. Audit Compliance: Maintaining a digital paper trail for every Rupee or Dollar that leaves the business account.

3. Customer Service: Empowering support teams to confirm "Yes, your refund was processed on [Date]" without asking the accounting department.

Manage Your Returns with Kalki LLP

Refunds are a natural part of business, but managing them manually is prone to error. Kalki LLP specializes in building automated refund-tracking workflows that keep your ledger clean and your customers informed.