Handling refunds with the TaxJar API

You can find the documentation for creating refund transactions here.

This call to our API supports partial refunds, with or without line item information (including product tax codes for exemptions), and multiple refund transactions referencing the original order transaction.

If you need to figure out how much tax should apply for the refund amount you could make a call to our  /v2/taxes endpoint to have TaxJar calculate the correct taxes. You would then take this information and provide it to your call that creates a refund transaction.

Also, keep in mind that when creating a refund transaction, the "transaction_id" must be a unique identifier for the refund and different from the original order "transaction_id" (do not use periods in IDs). The "transaction_reference_id" is used to reference and link to the original order transaction.


  • Refund for a specific item
    • A customer orders productA, productB, and productC and the order has a "transaction_id" of 123.
    • You need to refund productB, so you would send a call similar to this:
        "transaction_id": "123-refund",
        "transaction_date": "2018/06/14",
        "transaction_reference_id": "123",
        "to_country": "US",
        "to_zip": "90002",
        "to_state": "CA",
        "to_city": "Los Angeles",
        "to_street": "123 Palm Grove Ln",
        "amount": 16.50,
        "shipping": 1.5,
        "sales_tax": 1.43,
        "line_items": [
            "quantity": 1,
            "product_identifier": "productB",
            "description": "ProductB is a B product.",
            "unit_price": 15.0,
            "sales_tax": 1.43