# Credit Notes

Credit notes represent adjustments to a paid invoice. They are commonly used to issue refunds or credits
to your users, allow you to reduce your taxes owed, and reflect the adjustment on invoice PDFs. While
credit notes can cover the full amount of an invoice, certain taxes and fees may remain non-refundable
and still need to be remitted to tax authorities.

## When to use Credit Notes

Credit notes are the right tool when you need to:

- Issue a full or partial refund after a subscription has been paid
- Correct a billing error on a finalized invoice
- Reflect a retroactive discount or goodwill credit

Credit notes also make sure that Gigs charges you the correct amounts each month when refunds were made to your users.

## The credit note lifecycle

[Credit notes](/billing/credit-notes) can have one of the following statuses:

| Status   | Description                     | Possible Actions               |
| -------- | ------------------------------- | ------------------------------ |
| `issued` | The credit note was created.    | Change its status to `voided`. |
| `voided` | The credit note was canceled.   | No further action.             |

<Note type="info">
  Credit notes are created with `creditTo: outOfBand` by default, meaning you are responsible for
  processing the refund outside of Gigs (for example, through your own payment provider). In exceptional
  cases — such as a subscription restore — Gigs creates credit notes with `creditTo: userBalance`
  automatically. These are handled entirely by Gigs and do not require any action from you.
</Note>

## Creating a full credit note

To credit the full remaining balance of a paid invoice, provide only the `invoice` ID. Gigs will
automatically calculate and credit all remaining line item amounts, taxes, and fees. If the invoice has
already been partially credited, only the remaining uncredited amount will be included.

<CodeGroup title="Creating a full credit note">

```bash
curl --request POST \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/creditNotes" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25"
  }'
```

</CodeGroup>

## Creating a partial credit note

To credit only part of an invoice, specify the individual line items and their taxes by ID.
Each line item is identified by its `invoiceLineItem` ID from the original invoice and the `amount`
to credit in the invoice currency. Taxes are specified by their `invoiceTax` ID and amount.

If the original invoice included a recovery fee you want to credit, pass it in the `fees` array with
`type: recoveryFee`. This is the only supported fee type.

The sum of all credit notes issued for a given invoice cannot exceed the original invoice amounts.

<CodeGroup title="Creating a partial credit note">

```bash
curl --request POST \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/creditNotes" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "invoice": "inv_0SNlurA049MEWV1QTRqvd18YuG25",
    "lineItems": [
      {
        "invoiceLineItem": "lin_0SNlurA049MEWV11QUKZGDMxJmKe",
        "amount": 500,
        "taxes": [
          {
            "invoiceTax": "itx_0SNlurA049MEWV5Mw7cjrxFUo2Y3",
            "amount": 45
          }
        ]
      }
    ],
    "fees": [
      {
        "type": "recoveryFee",
        "amount": 100
      }
    ]
  }'
```

</CodeGroup>

You can credit line item amounts without crediting taxes, or credit taxes independently by omitting or
setting the `amount` field to `null` on a line item. The `fees` array is optional and only applies when
the original invoice included a recovery fee.

## Tax adjustments

Once a credit note is issued, Gigs automatically adjusts your tax calculations in the background to
reflect the reduced revenue. You don't need to take any action for this to happen.

<Note type="info">
  Some taxes — such as recovery fees — may be non-refundable depending on your project configuration.
  Even if you issue a credit note for these amounts, you may still be required to remit them to the
  relevant tax authorities.
</Note>

## Voiding a credit note

If you need to reverse a credit note, you can void it. Voiding cancels the credited amount and reverses
any associated tax adjustments. Once voided, the credit note has no further effect and cannot be reinstated.

<CodeGroup title="Voiding a credit note">

```bash
curl --request POST \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/creditNotes/cno_0SNlurA049MEWV6EhR4Pz3nDvXq/void" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"
```

</CodeGroup>

## Retrieving and listing credit notes

You can retrieve a specific credit note by its ID, or list all credit notes for a project. When listing,
you can filter by `invoice` to find all credit notes for a particular invoice, or by `status` to find
only `issued` or `voided` credit notes.

<CodeGroup title="Listing credit notes for an invoice">

```bash
curl --request GET \
  --url "https://api.gigs.com/projects/${GIGS_PROJECT}/creditNotes?invoice=inv_0SNlurA049MEWV1QTRqvd18YuG25" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer ${GIGS_TOKEN}"
```

</CodeGroup>

## Downloading the credit note PDF

Each credit note includes a `fileUrl` field with a signed URL to download the credit note as a PDF.
This field is only available for select projects and will be `null` for all others.