# Record refund for an invoice

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


[Idempotency Supported](/docs/api/idempotency)

[Asynchronous](/docs/api/async_response/async-response-object)

Record a full or partial offline refund for an invoice.

Use this API to record refunds processed outside Chargebee (for example, directly through a payment gateway or via offline methods such as bank transfers or checks) so you can reconcile them in Chargebee.

**Important:** This API does not process actual refunds for online payments or return money to customers through the payment gateway. To process refunds for online payments and return money to customers, use the [Refund an invoice](/docs/api/invoices/refund-an-invoice) API instead.

### Prerequisites & Constraints

The invoice must have a [refundable amount](/docs/api/invoices/invoice-object#refundable-amount). (See Implementation Notes for details.)

### Impacts

**

Credit note

**

Chargebee creates a `refundable` [credit note](/docs/api/credit_notes/credit-note-object) with [`status`](/docs/api/credit_notes/credit_note-object#status) set to `refunded`.

**

Transactions

**

Chargebee records the refunds by creating transactions of [`type`](/docs/api/transactions/transaction-object#type) `refund` and links them to the credit note. The refund transactions are recorded in the following order:

1.  [`linked_payments`](/docs/api/invoices/invoice-object#linked_payments) for offline transactions. This is recorded as [`linked_refunds[]`](/docs/api/credit_notes/credit_note-object#linked_refunds) in the credit note.
2.  [`linked_taxes_withheld`](/docs/api/invoices/invoice-object#linked_taxes_withheld) (if available). This is recorded as [`linked_tax_withheld_refunds[]`](/docs/api/credit_notes/credit_note-object#linked_tax_withheld_refunds) in the credit note.
3.  `linked_payments` for online transactions (after offline payments and taxes withheld are exhausted). This is recorded as [`linked_refunds[]`](/docs/api/credit_notes/credit_note-object#linked_refunds) in the credit note.

**Example**

Consider an invoice with the following payments and tax withheld:

-   Offline payments: $30
-   Online payments: $20
-   Tax withheld: $5

When you record a refund of $40, Chargebee allocates the refund as follows:

-   Refund against offline payments: $30
-   Refund against tax withheld: $5
-   Refund against online payments: $5

### Implementation Notes

Before calling this API, perform the following checks:

-   The invoice must have a [refundable amount](/docs/api/invoices/invoice-object#refundable-amount).
-   Ensure the `transaction[date]` is on or after the invoice date and not in the future.
-   Include the `transaction[amount]` parameter to specify the refund amount. If you omit this parameter, the system records the entire refundable amount as refunded.
-   If [reason codes](https://www.chargebee.com/docs/billing/2.0/site-configuration/reason-codes#managing-reason-codes-for-credit-notes) are mandatory in Chargebee Billing, include the `credit_note[create_reason_code]` parameter with a value from the configured list of codes.

## Sample Request

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__13/record_refund \
     -u {site_api_key}:\
     -d "transaction[amount]"=100 \
     -d "transaction[payment_method]"="BANK_TRANSFER" \
     -d "transaction[date]"=1517490274
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;
using ChargeBee.Models.Enums;

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Invoice.RecordRefund("__demo_inv__13")
		.TransactionAmount(100)
		.TransactionPaymentMethod(PaymentMethodEnum.BankTransfer)
		.TransactionDate(1517490274)
		.Request();

Invoice invoice = result.Invoice;
Transaction transaction = result.Transaction;
CreditNote creditNote = result.CreditNote;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    invoiceAction "github.com/chargebee/chargebee-go/v3/actions/invoice"
    "github.com/chargebee/chargebee-go/v3/models/invoice"
    enum "github.com/chargebee/chargebee-go/v3/enum"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := invoiceAction.RecordRefund("__demo_inv__13", &invoice.RecordRefundRequestParams{
        Transaction : &invoice.RecordRefundTransactionParams{
            Amount : chargebee.Int64(100),
            PaymentMethod : enum.PaymentMethodBankTransfer,
            Date : chargebee.Int64(1517490274),
        },
    }).Request()
    if err != nil {
        fmt.Println(err)
    } else {
        Invoice := res.Invoice
        Transaction := res.Transaction
        CreditNote := res.CreditNote
    }
}
```

#### Go

```go
package main

import (
  "fmt"
  "github.com/chargebee/chargebee-go/v4"
)

func main() {
  config := &chargebee.ClientConfig{
    SiteName: "{site}",
    ApiKey: "{site_api_key}",
  }    
  client := chargebee.NewClient(config)
  req := &chargebee.InvoiceRecordRefundRequest{
    Transaction : &chargebee.InvoiceRecordRefundTransaction{
        Amount : chargebee.Int64(100),
        PaymentMethod : chargebee.PaymentMethodBankTransfer,
        Date : chargebee.Int64(1517490274),
    },
}
  res, err := client.Invoice.RecordRefund("__demo_inv__13", req)
      if err != nil {
        fmt.Println(err)
    } else {
        Invoice := res.Invoice
        Transaction := res.Transaction
        CreditNote := res.CreditNote
    }
}
```

#### Java

```java
import com.chargebee.*;
import com.chargebee.ListResult;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
import java.io.IOException;
import java.sql.Timestamp;

public class Sample {

    public static void main(String args[]) throws IOException, Exception {
        Environment.configure("{site}", "{site_api_key}");
        Result result = Invoice.recordRefund("__demo_inv__13")
            .transactionAmount(100L)
            .transactionPaymentMethod(PaymentMethod.BANK_TRANSFER)
            .transactionDate(new Timestamp(1517490274L * 1000))
            .request();

        Invoice invoice = result.invoice();
        Transaction transaction = result.transaction();
        CreditNote creditNote = result.creditNote();
    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.creditNote.CreditNote;
import com.chargebee.v4.models.invoice.Invoice;
import com.chargebee.v4.models.invoice.params.InvoiceRecordRefundParams;
import com.chargebee.v4.models.invoice.responses.InvoiceRecordRefundResponse;
import com.chargebee.v4.models.transaction.Transaction;
import java.sql.Timestamp;

public class InvoiceRecordRefund {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        InvoiceRecordRefundParams.TransactionParams transactionParams =
            InvoiceRecordRefundParams.TransactionParams.builder()
                .amount(100L)
                .paymentMethod(InvoiceRecordRefundParams.TransactionParams.PaymentMethod.BANK_TRANSFER)
                .date(new Timestamp(1517490274L * 1000))
                .build();

        InvoiceRecordRefundParams params = InvoiceRecordRefundParams.builder()
            .transaction(transactionParams)
            .build();

        InvoiceRecordRefundResponse response = client
            .invoices()
            .recordRefund("__demo_inv__13", params);

        Invoice invoice = response.getInvoice();
        Transaction transaction = response.getTransaction();
        CreditNote creditNote = response.getCreditNote();
    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

const chargebee = new Chargebee({
    site: "{site}",
    apiKey: "{site_api_key}",
});

try {
    const result = await chargebee.invoice.recordRefund("__demo_inv__13", {
        transaction: {
            amount: 100,
            payment_method: "bank_transfer",
            date: 1517490274
        }
    });

    console.log(result);
    const invoice = result.invoice;
    const transaction = result.transaction;
    const creditNote = result.credit_note;
} catch (err) {
    console.log(err);
}
```

#### PHP

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->invoice()->recordRefund("__demo_inv__13", [
    "transaction" => [
        "amount" => 100,
        "payment_method" => "bank_transfer",
        "date" => 1517490274
    ]
]);
$invoice = $result->invoice;
$transaction = $result->transaction;
$creditNote = $result->credit_note;
```

#### Python

```python
import chargebee
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.Invoice.record_refund("__demo_inv__13",
    cb_client.Invoice.RecordRefundParams(
        transaction=cb_client.Invoice.RecordRefundTransactionParams(
            amount=100,
            payment_method=chargebee.PaymentMethod.BANK_TRANSFER,
            date=1517490274
        )
    )
)
invoice = response.invoice
transaction = response.transaction
credit_note = response.credit_note
```

#### Ruby

```ruby
require 'chargebee'

ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")

result = ChargeBee::Invoice.record_refund("__demo_inv__13",{
  :transaction => {
    :amount => 100,
    :payment_method => "BANK_TRANSFER",
    :date => 1517490274
  }
})

invoice = result.invoice
transaction = result.transaction
credit_note = result.credit_note
```

## Sample Response

```json
{
  "credit_note": {
    "allocations": {},
    "amount_allocated": 0,
    "amount_available": 0,
    "amount_refunded": 100,
    "base_currency_code": "USD",
    "create_reason_code": "Other",
    "currency_code": "USD",
    "customer_id": "__test__8asyKSOcTK1x2z",
    "date": 1517490274,
    "deleted": false,
    "exchange_rate": 1,
    "fractional_correction": 0,
    "id": "__demo_cn__3",
    "line_item_discounts": {},
    "line_item_taxes": {},
    "line_items": [
      {
        "amount": 100,
        "customer_id": "__test__8asyKSOcTK1x2z",
        "date_from": 1517490274,
        "date_to": 1517490274,
        "description": "SSL Charge USD Monthly",
        "discount_amount": 0,
        "entity_id": "ssl-charge-USD",
        "entity_type": "charge_item_price",
        "id": "li___test__8asyKSOcTKBX3F",
        "is_taxed": false,
        "item_level_discount_amount": 0,
        "object": "line_item",
        "pricing_model": "flat_fee",
        "quantity": 1,
        "tax_amount": 0,
        "tax_exempt_reason": "tax_not_configured",
        "unit_amount": 100
      },
      {..}
    ],
    "linked_refunds": [
      {
        "applied_amount": 100,
        "applied_at": 1517490274,
        "txn_amount": 100,
        "txn_date": 1517490274,
        "txn_id": "txn___test__8asyKSOcTKBP3D",
        "txn_status": "success"
      },
      {..}
    ],
    "object": "credit_note",
    "price_type": "tax_exclusive",
    "reason_code": "other",
    "reference_invoice_id": "__demo_inv__13",
    "refunded_at": 1517490274,
    "resource_version": 1517490274234,
    "round_off_amount": 0,
    "status": "refunded",
    "sub_total": 100,
    "taxes": {},
    "total": 100,
    "type": "refundable",
    "updated_at": 1517490274
  },
  "invoice": {
    "adjustment_credit_notes": {},
    "amount_adjusted": 0,
    "amount_due": 0,
    "amount_paid": 500,
    "amount_to_collect": 0,
    "applied_credits": {},
    "base_currency_code": "USD",
    "billing_address": {
      "first_name": "John",
      "last_name": "Mathew",
      "object": "billing_address",
      "validation_status": "not_validated"
    },
    "credits_applied": 0,
    "currency_code": "USD",
    "customer_id": "__test__8asyKSOcTK1x2z",
    "date": 1517490273,
    "deleted": false,
    "due_date": 1517490273,
    "dunning_attempts": {},
    "exchange_rate": 1,
    "first_invoice": true,
    "has_advance_charges": false,
    "id": "__demo_inv__13",
    "is_gifted": false,
    "issued_credit_notes": [
      {
        "cn_create_reason_code": "Other",
        "cn_date": 1517490274,
        "cn_id": "__demo_cn__3",
        "cn_reason_code": "other",
        "cn_status": "refunded",
        "cn_total": 100
      },
      {..}
    ],
    "line_items": [
      {
        "amount": 500,
        "customer_id": "__test__8asyKSOcTK1x2z",
        "date_from": 1517490273,
        "date_to": 1517490273,
        "description": "SSL Charge USD Monthly",
        "discount_amount": 0,
        "entity_id": "ssl-charge-USD",
        "entity_type": "charge_item_price",
        "id": "li___test__8asyKSOcTK6f37",
        "is_taxed": false,
        "item_level_discount_amount": 0,
        "object": "line_item",
        "pricing_model": "flat_fee",
        "quantity": 1,
        "tax_amount": 0,
        "tax_exempt_reason": "tax_not_configured",
        "unit_amount": 500
      },
      {..}
    ],
    "linked_orders": {},
    "linked_payments": [
      {
        "applied_amount": 500,
        "applied_at": 1517490274,
        "txn_amount": 500,
        "txn_date": 1517490274,
        "txn_id": "txn___test__8asyKSOcTKA438",
        "txn_status": "success"
      },
      {..}
    ],
    "net_term_days": 0,
    "new_sales_amount": 500,
    "object": "invoice",
    "paid_at": 1517490274,
    "price_type": "tax_exclusive",
    "recurring": false,
    "resource_version": 1517490274233,
    "round_off_amount": 0,
    "status": "paid",
    "sub_total": 500,
    "tax": 0,
    "term_finalized": true,
    "total": 500,
    "updated_at": 1517490274,
    "write_off_amount": 0
  },
  "transaction": {
    "amount": 100,
    "base_currency_code": "USD",
    "currency_code": "USD",
    "customer_id": "__test__8asyKSOcTK1x2z",
    "date": 1517490274,
    "deleted": false,
    "exchange_rate": 1,
    "gateway": "not_applicable",
    "id": "txn___test__8asyKSOcTKBP3D",
    "linked_credit_notes": [
      {
        "applied_amount": 100,
        "applied_at": 1517490274,
        "cn_create_reason_code": "Other",
        "cn_date": 1517490274,
        "cn_id": "__demo_cn__3",
        "cn_reason_code": "other",
        "cn_reference_invoice_id": "__demo_inv__13",
        "cn_status": "refunded",
        "cn_total": 100
      },
      {..}
    ],
    "object": "transaction",
    "payment_method": "bank_transfer",
    "resource_version": 1517490274235,
    "status": "success",
    "type": "refund",
    "updated_at": 1517490274
  }
}
```

## URL Format

**POST** https://[site].chargebee.com/api/v2/invoices/{invoice-id}/record_refund

## Input Parameters

- `comment` (optional, string, max chars=65k)
  Remarks, if any, on the refund.

- `customer_notes` (optional, string, max chars=2000)
  The Customer Notes to be filled in the Credit Notes created to capture this refund detail.

- `transaction` (optional, in cents)
  Parameters for transaction
  - `amount` (optional, in cents, min=0)
    The amount to be refunded (for online payments) or recorded as refunded (for offline payments). If not specified, the entire refundable amount for this invoice is refunded. The refundable amount is the total amount paid (and not already refunded) for the invoice.
    
    **Note:** Any `[linked_taxes_withheld](/docs/api/invoices/invoice-object#linked_taxes_withheld)` associated with the invoice can also be recorded as refunded via this operation.
  - `payment_method` (required, enumerated string)
    The payment method of this transaction
    Possible enum values:
      - `cash`
        Cash
      - `check`
        Check
      - `chargeback`
        Only applicable for a transaction of `[type](/docs/api/transactions/transaction-object#type)` = `refund`. This value is set by Chargebee when an automated [chargeback](https://www.chargebee.com/docs/chargeback.html#chargeback-process) occurs. You can also set this explicitly when [recording a refund](/docs/api/transactions/record-an-offline-refund) .
      - `bank_transfer`
        Bank Transfer
      - `other`
        Payment Methods other than the above types
      - `custom`
        Custom
      - `tamara`
      - `qpay`
      - `blik`
      - `fpx`
      - `wero`
      - `p24`
      - `affirm_pay`
  - `reference_number` (optional, string, max chars=100)
    The reference number for this transaction. For example, the check number when `[payment_method](/docs/api/transactions/transaction-object#payment_method)` = `check` .
  - `custom_payment_method_id` (optional, string, max chars=50)
    Identifier of the custom payment method of this transaction.
  - `date` (required, timestamp(UTC) in seconds)
    Indicates when this transaction occurred.

- `credit_note` (optional, enumerated string)
  Parameters for credit\_note
  - `reason_code` (optional, enumerated string)
    The reason for issuing this Credit Note. The following reason codes are supported now\[Deprecated; use the [create\_reason\_code](/docs/api/credit_notes/credit_note-object#create_reason_code) parameter instead\]
    Possible enum values:
      - `chargeback`
        Can be set when you are recording your customer Chargebacks
      - `product_unsatisfactory`
        Product Unsatisfactory
      - `service_unsatisfactory`
        Service Unsatisfactory
      - `order_change`
        Order Change
      - `order_cancellation`
        Order Cancellation
      - `waiver`
        Waiver
      - `other`
        Can be set when none of the above reason codes are applicable
  - `create_reason_code` (optional, string, max chars=100)
    Reason code for creating the credit note. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Credit Notes > Create Credit Note. The codes are case-sensitive

## Returns

- `invoice` (Invoice object)
  Resource object representing invoice

- `transaction` (Transaction object)
  Resource object representing transaction

- `credit_note` (Credit note object)
  Resource object representing credit\_note