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 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.

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.

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.

Creating a full credit note

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"
  }'

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.

Creating a partial credit note

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
      }
    ]
  }'

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.

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.

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.

Voiding a credit note

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

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.

Listing credit notes for an invoice

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

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.