Create or use a credit note

Credit notes correct an issued invoice without mutating its frozen fiscal history. Invoice supports total and partial credit notes through PHP services, then registers the result in the same Factur-X compliance pipeline.

See Credit notes first for the accounting model and Invoice data for the immutable snapshot contract.

Common prerequisites

You need:

• the original Sylius invoice entity;
• its ImmutableInvoiceSnapshot;
• a unique credit-note number managed by your application;
• an issue date that is not earlier than the corrected invoice;
• a PDF rendition of the credit note to use as the visual base for Factur-X registration.

The source invoice stays unchanged throughout the operation.

Create a total credit note

Inject TotalCreditNoteFactory and create the electronic credit note from the frozen snapshot:

use DateTimeImmutable;
use SyliusInvoicePlugin\CreditNote\TotalCreditNoteFactory;

$creditNote = $totalCreditNoteFactory->create(
    $sourceSnapshot,
    'CN-2026-0001',
    new DateTimeImmutable('2026-08-21'),
);

$sourceSnapshot is the immutable snapshot belonging to the invoice being corrected. The factory rejects an empty credit-note number and a date earlier than the source invoice. The result references the original invoice number/date and reproduces the frozen lines, taxes and totals without mutating the source snapshot.

A total credit note is the appropriate Invoice primitive for a complete commercial reversal. See Cancel an invoice.

Create a partial credit note

Inject PartialCreditNoteService and select source lines by zero-based line index and quantity:

use DateTimeImmutable;
use SyliusInvoicePlugin\CreditNote\PartialCreditNoteLineSelection;
use SyliusInvoicePlugin\CreditNote\PartialCreditNoteService;

$creditNote = $partialCreditNoteService->create(
    $sourceSnapshot,
    'CN-2026-0002',
    new DateTimeImmutable('2026-08-21'),
    [
        new PartialCreditNoteLineSelection(lineIndex: 1, quantity: 1),
    ],
);

The service runs the quantity reservation and allocation recording transactionally. It recalculates the selected quantities, discounts and taxes from the frozen source data.

It rejects:

• an empty selection list;
• a negative line index;
• a quantity less than or equal to zero;
• a line index that does not exist in the source snapshot;
• a quantity that exceeds what remains creditable for that line;
• duplicate credit-note allocations that violate the source/number/line uniqueness contract.

Register the credit note as a compliance document

After your application has rendered the credit note PDF, register it with CreditNoteComplianceDocumentRegistrar:

use SyliusInvoicePlugin\CreditNote\CreditNoteComplianceDocumentRegistrar;

$document = $creditNoteRegistrar->register(
    $sourceInvoice,
    $creditNote,
    $creditNotePdfContent,
);

$sourceInvoice is the original Sylius invoice entity and $creditNotePdfContent is the PDF rendering of the credit note, not a mutable replacement of the original invoice PDF.

Registration verifies that the electronic document is a credit note and that its corrected-invoice reference matches the linked Sylius invoice. It then:

1. generates the Factur-X PDF and structured XML;
2. stores their integrity hashes;
3. validates the electronic document;
4. persists the compliance document;
5. dispatches transmission only when automatic transmission is configured.

Registration is deterministic for the same source invoice and credit-note number. Re-registering a complete matching document reuses it; an incomplete or integrity-failing existing document is rejected rather than silently overwritten.

Expected result

A successful operation leaves both documents represented explicitly:

• the original invoice remains immutable and traceable;
• the credit note has its own number and issue date;
• the credit note references the corrected invoice;
• its Factur-X/XML artefacts are validated and governed by the same integrity rules as invoices.

Use Download an invoice to retrieve governed compliance artefacts from the Admin once the credit-note compliance document is registered.