Credit notes

A credit note records a reduction against a finalized invoice — for a refund, a billing correction, or goodwill — without rewriting history. The original invoice stays immutable; the credit note is a separate, auditable document that adjusts what the customer owes (or gets back). This matters because finalized invoices are legal records: you correct them by crediting, never by editing.

When to issue a credit noteAskCopy

Reach for a credit note whenever a finalized invoice over-charged the customer or the relationship needs an adjustment after the fact.

Creating a credit noteAskCopy

You can credit specific line items or a flat amount. The SDK validates the total against the invoice before VINR finalizes the note.

import { Vinr } from '@vinr/sdk';
const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

// Credit one line item from a finalized invoice.
const note = await vinr.creditNotes.create({
  invoice: 'inv_8Q2pK',
  lines: [
    {
      type: 'invoice_line_item',
      invoiceLineItem: 'il_4Tm9c',
      quantity: 2,                 // credit 2 of the billed seats
    },
  ],
  memo: 'Returned 2 seats on 2026-05-30',
  reason: 'product_unsatisfactory',
});

console.log(note.id);              // "cn_..." 
console.log(note.total);           // e.g. 4000 → EUR 40.00 credited

To credit a flat amount instead of line items — useful for goodwill — pass amount and a creditAmount split:

const goodwill = await vinr.creditNotes.create({
  invoice: 'inv_8Q2pK',
  amount: 1000,                    // EUR 10.00
  reason: 'goodwill',
  creditAmount: 1000,              // apply entirely to the customer balance
});

Refund vs. credit balanceAskCopy

Every credit note splits its total into two buckets, and you decide the split at creation time:

// Half back to the card, half toward the next invoice.
await vinr.creditNotes.create({
  invoice: 'inv_8Q2pK',
  amount: 2000,
  refundAmount: 1000,             // EUR 10.00 → original card
  creditAmount: 1000,             // EUR 10.00 → customer balance
  reason: 'order_change',
});

Impact on revenueAskCopy

A credit note reverses recognized revenue for the credited portion, dated to the note's creation — it never back-dates the original invoice. Two consequences worth internalizing:

Tax is reversed proportionally: credit two of five taxed seats and VINR backs out the tax on those two. See Tax for how reversals appear in your filings.

ReportingAskCopy

Credit notes carry a status (issued or void) and surface in the same exports as invoices. Listen for events to keep downstream ledgers in sync:

// Webhook handler (Edge or Node).
const event = vinr.webhooks.verify(payload, signature); // x-vinr-signature

switch (event.type) {
  case 'credit_note.issued':
    ledger.recordCredit(event.data.object);
    break;
  case 'credit_note.voided':
    ledger.reverseCredit(event.data.object);
    break;
}

A note can be voided only while none of it has been refunded or spent against a balance; once any portion is consumed it is permanent. Pull a period's notes for reconciliation with vinr.creditNotes.list({ invoice, status: 'issued' }), or export them alongside invoices from Operations → reports.

Next stepsAskCopy