Refunds

Learn about how you can model refunds and how these are processed.

Modelling Refunds

You use the Create a Refund request to issue refunds and credit notes. See Create a refund.

To create a refund, you use a POST method and the following URL:

https://services.taxamo.com/api/v2/transactions/{key}/refunds/

where {key} is the Transaction Key of the transaction that you wish to refund.

You can specify details in the URL or in the body of the request. See Refunds Schema.

The following example specifies the Transaction Key, the Line Key and the Amount in the URL:

$ curl -X 'POST' 'https://services.taxamo.com/api/v2/transactions/T60YAAAABteWsHwfho8xUz1l4fuo/refunds?line_key=SQ0Kuuvp4P9VnEzq&private_token=priv_***********&total_amount=100'

Refund Types

There are 3 types of refunds:

  • Transaction: When a refund is applied to the entire transaction.
  • Transaction-line: When a refund is applied to a single line of a transaction. You can only refund a single line_key in each Create Refund request.
  • Bulk Refund endpoint: When a refund is applied to multiple lines in a single request. You use the Bulk Refunds request for these types of refunds.

Transaction Refunds

To refund a transaction completely or partially, you can specify the required amount of the transaction in the total_amount field.

If no line_key or custom_id is specified, the refund is distributed to the first line and subsequent lines until the refund amount is exhausted.

For example:

  {
           "total_amount": 5000,
           "refund_reason": "Faulty goods"
        }

Transaction Line Refunds

πŸ“˜

Note

You can only refund a single line_key in each Create Refund request. For example, if you want to refund 3 lines in a transaction, you must send 3 requests, 1 for each line_key.

To refund a transaction line completely or partially, you can specify the line_key for the line that you want the amount to be applied to. For example:

{
           "line_key": "SQ0Kuuvp4P9VnEzq&",
           "amount": 10,
           "refund_reason": "Substitution"
        }

Alternatively, you can use the custom_id field to identify the transaction line. This approach allows you to identify the transaction line without using the line_key. You must add the Custom ID to the transaction line before you create the refund.

For example:

{
           "custom_id": "customID_1",
           "amount": 10,
           "refund_reason": "Replacement"
        }

Bulk Refunds API

If you want to refund multiple transaction lines in a single request, you can use the Bulk Refunds request. You can use either the line_key or custom_id fields to specify which lines are to be refunded. This allows you to refund multiple transaction lines in a single request, resulting in a single credit.

US and Canadian Refunds

Some extra fields are available for US and Canadian discounts. See US and Canadian Refunds (Tax Components Schema).

Informative Transactions and Refunds

If you want to do an informative refund, you can use the informative: true field. However, the transaction line that you refund must also be informative.

Refund Processing

The following diagram shows the process flow for a refund:

Refund Processing

Refund Processing

The steps are as follows:

  1. Buyer requests refund. The buyer requests a refund, a reason is provided and the refund is approved by the merchant.
  2. A Create a refund request is sent that contains the refund details in the attached JSON. This example uses a custom_id to specify the transaction line:
{
           "custom_id": "customID_1",
           "amount": 10,
           "refund_reason": "Broken goods"
        }
  1. The Create a refund response returns the tax information in the attached JSON. Here, you can specify whether this is a transaction- or line-level refund. In this example, it is a line-level refund:
{
    "refund_reason": "Broken goods",
    "amount": 10.00,
    "refunded_amount": 10.00,
    "refund_timestamp": "2024-03-21T14:17:54Z",
    "tax_amount": 0.88,
    "refunded_tax_amount": 0.88,
    "refunded_total_amount": 10.88,
    "refund_key": "xyIovZMgd6daTA",
    "total_amount": 10.88,
    "refunds": [
        {
            "refund_reason": "Broken goods",
            "amount": 10.00,
            "informative": null,
            "refunded_amount": 10.00,
            "refund_timestamp": "2024-03-21T14:17:54Z",
            "tax_amount": 0.88,
            "refund_note_url": null,
            "tax_rate": 8.81,
            "line_key": "96LuL-XuL3s4iqZK",
            "custom_id": "customID_1",
            "refunded_tax_amount": 0.88,
            "refund_note_number": null,
            "refunded_total_amount": 10.88,
            "refund_key": "xyIovZMgd6daTA",
            "total_amount": 10.88,
            "refund_unique_id": null,
            "tax_components": [
                {
                    "revenue": 10.00,
                    "tax_amount": 0.29,
                    "tax_result": "TAXABLE",
                    "city": "DENVER",
                    "tax_rate": 2.9,
                    "county": "DENVER",
                    "tax_authority_name": "COLORADO",
                    "refunded_tax_amount": 0.29,
                    "tax_authority_id": "4220",
                    "tax_name": "Sales and Use Tax",
                    "revenue_base": 10.00,
                    "percent_taxable": 1,
                    "jurisdiction_code": "4220",
                    "state_code": "CO",
                    "jurisdiction_type": "STATE"
                },
                {
                    "revenue": 10.00,
                    "tax_amount": 0.48,
                    "tax_result": "TAXABLE",
                    "city": "DENVER",
                    "tax_rate": 4.81,
                    "county": "DENVER",
                    "tax_authority_name": "DENVER",
                    "refunded_tax_amount": 0.48,
                    "tax_authority_id": "4372",
                    "tax_name": "Local Sales and Use Tax",
                    "revenue_base": 10.00,
                    "percent_taxable": 1,
                    "jurisdiction_code": "4372",
                    "state_code": "CO",
                    "jurisdiction_type": "CITY"
                },
                {
                    "revenue": 10.00,
                    "tax_amount": 0.10,
                    "tax_result": "TAXABLE",
                    "city": "DENVER",
                    "tax_rate": 1,
                    "county": "DENVER",
                    "tax_authority_name": "REGIONAL TRANSPORTATION DISTRICT",
                    "refunded_tax_amount": 0.10,
                    "tax_authority_id": "78135",
                    "tax_name": "Local Sales and Use Tax",
                    "revenue_base": 10.00,
                    "percent_taxable": 1,
                    "jurisdiction_code": "78135",
                    "state_code": "CO",
                    "jurisdiction_type": "DISTRICT"
                },
                {
                    "revenue": 10.00,
                    "tax_amount": 0.01,
                    "tax_result": "TAXABLE",
                    "city": "DENVER",
                    "tax_rate": 0.1,
                    "county": "DENVER",
                    "tax_authority_name": "SCIENTIFIC AND CULTURAL FACILITIES DISTRICT",
                    "refunded_tax_amount": 0.01,
                    "tax_authority_id": "78399",
                    "tax_name": "Local Sales and Use Tax",
                    "revenue_base": 10.00,
                    "percent_taxable": 1,
                    "jurisdiction_code": "78399",
                    "state_code": "CO",
                    "jurisdiction_type": "DISTRICT"
                }
            ]
        }
    ]
}
  1. Refund details are displayed on the merchant's UI. The merchant can use the returned details as they choose.
  2. Credit note is sent to the buyer. Where applicable, the credit note is sent to the buyer.
  3. Buyer receives credit note. The credit note is sent to the buyer, per the merchant's configuration. It can be sent as a URL or linked on the UI for download.

Refund Retrieval

You can use the Get transaction refunds request to retrieve a list all refunds.