> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bouclay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Refunds, credit notes and chargebacks

> Give money back, correct an invoice, and record a disputed payment

## Refunds

Refund a payment, in full or in part:

```bash theme={null}
curl https://bouclay.com/api/v1/payments/pay_…/refunds \
  -H "Authorization: Bearer $BOUCLAY_KEY" \
  -H "Idempotency-Key: refund-pay-123-1" \
  -H "Content-Type: application/json" \
  -d '{"amount": 2000, "reason": "Charged twice for March"}'
```

* Leave out `amount` to refund everything not yet refunded.
* The refund goes back through the gateway that took the payment, to the same card.
* A partial refund leaves the payment `succeeded`, and `amountRefunded` shows the running total.
* Every refund also issues a credit note against the invoice, with the tax inside it reversed, so your books stay right.

Find a payment's id on its invoice, as `payment.id`.

## Credit notes

A credit note corrects an issued invoice. Use it when you want to lower what an invoice owes, or give back money in a way other than a card refund.

```bash theme={null}
curl https://bouclay.com/api/v1/invoices/inv_…/credit-notes \
  -H "Authorization: Bearer $BOUCLAY_KEY" \
  -H "Idempotency-Key: cn-inv-123-1" \
  -H "Content-Type: application/json" \
  -d '{"amount": 5000, "reason": "Service outage on 3 March", "destination": "balance"}'
```

* **How much.** `amount` is spread over the invoice's lines in proportion to what is left on each. Or credit named lines with `lines`. Amounts include tax, and the tax inside is reversed at the rate the invoice was issued with.
* **On an unpaid invoice,** the credit lowers what is owed. Credited down to nothing, the invoice is marked `paid` with no payment.
* **On a paid invoice,** say where the money goes with `destination`:

| `destination` | The money goes |
| - | - |
| `refund` | Back to the card that paid (also needs `refunds:write`). |
| `balance` | To the customer's [balance](https://docs.bouclay.com/credits/overview.md#customer-balance), to pay their next invoices. |
| `outside` | Nowhere through Bouclay: you paid it back another way, such as a bank transfer. |

Credit notes have their own unbroken number sequence, and the customer gets an email with each one.

## Refunding a seat added by mistake

Seat increases are billed straight away for the rest of the period. To undo one the customer didn't mean to add:

1. Find the invoice the change raised: the customer's newest after the item change.
2. Refund its payment with `POST /payments/{id}/refunds`. The credit note comes with it.
3. Put the quantity back with `PATCH /subscriptions/{id}/items/{item}` and `"prorationBehavior": "none"`, so nothing else is billed or credited.

## Chargebacks

A chargeback is when a customer's bank takes a payment back, usually because the customer disputed it. Your gateway tells you; record it in Bouclay so your books and the subscription reflect it:

```bash theme={null}
curl https://bouclay.com/api/v1/payments/pay_…/chargebacks \
  -H "Authorization: Bearer $BOUCLAY_KEY" \
  -H "Idempotency-Key: cb-dispute-8812" \
  -H "Content-Type: application/json" \
  -d '{"reference": "DSP-8812", "reason": "Customer did not recognise the charge"}'
```

* `reference` is the gateway's dispute id. Sending the same one again returns the chargeback already recorded, so a repeated notice counts once.
* `amount` is optional: leave it out for everything not yet charged back.
* Nothing is sent to the gateway. The bank already took the money.
* While a chargeback is `open`, the subscription isn't charged or chased.
* A chargeback on a credit top-up takes back the credit not yet spent.

When the dispute ends, record the outcome:

```bash theme={null}
curl https://bouclay.com/api/v1/chargebacks/cb_…/resolve \
  -H "Authorization: Bearer $BOUCLAY_KEY" \
  -H "Idempotency-Key: cb-8812-won" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "won"}'
```

`won` means the bank returned the money: the payment no longer counts it as charged back, and any credit the chargeback took is put back. `lost` changes nothing else. Either way the subscription is charged and chased again once none of its chargebacks is open.

> [!NOTE]
>
> Bouclay doesn't read your gateway's dispute notices automatically yet, so record chargebacks yourself as they arrive.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.