# Credit notes

> Create, retrieve, void, and list credit notes that adjust finalized invoices.

A credit note adjusts a finalized [invoice](/docs/api-reference/invoices) — for example when a
customer was overcharged or a partial refund is due. Credit notes reduce the invoice's amount due
without modifying the original invoice.

> **Illustrative content.** Hand-authored to demonstrate the Standard/Advanced pattern; the production
> page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.

## The credit note object

- **id** `string` — Unique identifier for the credit note, e.g. `cn_6Dp3fQwH`.
- **invoice** `string` (expandable) — The ID of the invoice this credit note adjusts, e.g. `inv_1Ab5cDe6`. Expand to retrieve the
  full invoice object.
- **amount** `integer` — The credit amount in the smallest currency unit, e.g. `1500` for €15.00.
- **currency** `string` — Three-letter ISO currency code matching the invoice, e.g. `EUR`.
- **status** `enum` — Current state of the credit note: `issued` or `void`.
- **reason** `enum` — Why the credit was issued: `duplicate`, `fraudulent`, `order_change`, or `product_unsatisfactory`.
- **memo** `string` — Optional free-text note shown on the credit note PDF.
- **created** `integer` — Unix timestamp of when the credit note was created, e.g. `1716300000`.

## Create a credit note

Pass the `invoice` ID, the `amount` to credit, and a `reason`. The credit note is immediately
issued and the invoice's amount due is reduced.

`POST /v1/credit-notes`

```bash
curl -X POST https://api.vinr.com/v1/credit-notes \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d invoice=inv_1Ab5cDe6 \
-d amount=1500 \
-d reason=order_change \
-d memo="Partial refund for unused period"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const creditNote = await vinr.creditNotes.create({
invoice: 'inv_1Ab5cDe6',
amount: 1500,
reason: 'order_change',
memo: 'Partial refund for unused period',
});
```

```python
import vinr

credit_note = vinr.CreditNote.create(
  invoice="inv_1Ab5cDe6",
  amount=1500,
  reason="order_change",
  memo="Partial refund for unused period",
)
```

```ruby
credit_note = Vinr::CreditNote.create(
invoice: 'inv_1Ab5cDe6',
amount: 1500,
reason: 'order_change',
memo: 'Partial refund for unused period',
)
```

```json
{
"id": "cn_6Dp3fQwH",
"invoice": "inv_1Ab5cDe6",
"amount": 1500,
"currency": "EUR",
"status": "issued",
"reason": "order_change",
"memo": "Partial refund for unused period",
"created": 1716300000
}
```

## Retrieve a credit note

`GET /v1/credit-notes/{id}`

```bash
curl https://api.vinr.com/v1/credit-notes/cn_6Dp3fQwH \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const creditNote = await vinr.creditNotes.retrieve('cn_6Dp3fQwH');
```

```python
import vinr

credit_note = vinr.CreditNote.retrieve("cn_6Dp3fQwH")
```

```ruby
credit_note = Vinr::CreditNote.retrieve('cn_6Dp3fQwH')
```

```json
{
"id": "cn_6Dp3fQwH",
"invoice": "inv_1Ab5cDe6",
"amount": 1500,
"currency": "EUR",
"status": "issued",
"reason": "order_change",
"memo": "Partial refund for unused period",
"created": 1716300000
}
```

## Void a credit note

Voiding moves the credit note to `void` status and reverses its effect on the invoice's amount due.
Only `issued` credit notes can be voided.

`POST /v1/credit-notes/{id}/void`

```bash
curl -X POST https://api.vinr.com/v1/credit-notes/cn_6Dp3fQwH/void \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const creditNote = await vinr.creditNotes.void('cn_6Dp3fQwH');
```

```python
import vinr

credit_note = vinr.CreditNote.void("cn_6Dp3fQwH")
```

```ruby
credit_note = Vinr::CreditNote.void('cn_6Dp3fQwH')
```

```json
{
"id": "cn_6Dp3fQwH",
"invoice": "inv_1Ab5cDe6",
"amount": 1500,
"currency": "EUR",
"status": "void",
"reason": "order_change",
"memo": "Partial refund for unused period",
"created": 1716300000
}
```

## List credit notes

`GET /v1/credit-notes`

```bash
curl "https://api.vinr.com/v1/credit-notes?invoice=inv_1Ab5cDe6&limit=10" \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const creditNotes = await vinr.creditNotes.list({
invoice: 'inv_1Ab5cDe6',
limit: 10,
});
```

```python
import vinr

credit_notes = vinr.CreditNote.list(
  invoice="inv_1Ab5cDe6",
  limit=10,
)
```

```ruby
credit_notes = Vinr::CreditNote.list(
invoice: 'inv_1Ab5cDe6',
limit: 10,
)
```

```json
{
"object": "list",
"data": [
  {
    "id": "cn_6Dp3fQwH",
    "invoice": "inv_1Ab5cDe6",
    "amount": 1500,
    "currency": "EUR",
    "status": "issued",
    "reason": "order_change",
    "created": 1716300000
  }
],
"has_more": false
}
```

## Related events

`credit_note.created` and `credit_note.voided`. See [Events](/docs/api-reference/events).