Pixi API documentation

Unofficial · by koempf24.de

Postman collection
Invoices Write

pixiManualCreditCreate

Creates a manual credit note (negative invoice) for an existing invoice with a single amount and VAT rate.

Creates a credit note that references an existing invoice. The credit has no item lines; it consists of one amount and one VAT rate.

  1. Validation
    • Amount must be greater than 0.
    • VATRate must be H, L or N.
    • At least one of InvoiceKey or InvoiceNr must be given. If only InvoiceNr is given, the key is looked up in Invoices. The invoice must exist. If both are given, they must belong to the same invoice.
  2. Invoice data: order type, invoice location, customer, billing and shipping address and currency are taken from the original invoice. The country comes from the billing address.
  3. Position text: if PositionText is empty, a default text is built. With LanguageId = 1 it is Manual Credit: Created From: {InvoiceNr}. Otherwise it is Manuell Gutschrift: Erstellt von: {InvoiceNr}. LanguageId defaults to 2.
  4. VAT calculation: the VAT rates for the country and order type are read with Pixi_CA_GetVATList. The row with the requested VATRate is used.
    • For order type B2B, Amount is treated as net: net = −Amount, gross = −Amount × (1 + VAT), rounded to 2 decimals.
    • For all other order types, Amount is treated as gross: gross = −Amount, net = −Amount / (1 + VAT), rounded to 2 decimals.
  5. Limit check: the absolute gross amount of the new credit is added to the absolute sum of the totals of all invoices that already reference the original invoice (RefToInvoiceKey). If the result is greater than the original invoice total, the call is rejected.
  6. Creation: Pixi_CA_InsertManualInvoice creates the credit. It does the following:
    • assigns the next invoice number;
    • inserts the record into Invoices with RefToInvoiceKey/RefToInvoiceNr pointing to the original invoice;
    • adds SEPA data and an InvoicePackage record;
    • books the credit to the customer account;
    • publishes the MQ event InvoiceCreated.

The call returns one status row with Status and Message.

Notes

  • The call runs in its own transaction. If a transaction is already open, it uses a savepoint instead. Validation errors roll back and return return code 2. Unexpected errors are logged via log.InsertError and return return code 3. Success returns 0. Return codes are not part of the SOAP rows.
  • Always pass Amount and VATRate. A NULL value does not trigger the validation checks, because comparisons with NULL are not true. The calculated totals then stay NULL, and the limit check is skipped as well.
  • The same applies when the VAT list contains no row for the requested VATRate, for example L for a country without a reduced rate. Totals stay NULL.
  • Pixi_CA_GetVATList can return both the current rate and a rate valid 12 months ago for the same VATRate. Which row is used for the calculation is then not determined by the code.
  • The limit check adds the absolute value of the sum of existing referencing invoices, not the sum of absolute values.
  • Invoice lookups use NOLOCK, so concurrent credits for the same invoice are not strictly prevented from exceeding the invoice total.
  • Pixi_CA_InsertManualInvoice catches its own errors, logs them and does not re-raise them. If it fails, the caller may still receive the OK row. This can be followed by an Error row if the final commit fails because the transaction was already rolled back.
  • The text of the generic error (...getting the report values...) is misleading; it covers any unexpected error of this call.
  • The inner procedures Pixi_GetNextInvNr, Pixi_CA_AddPixiInvoice, Pixi_AddDataForSEPAExportToInvoice and Pixi_MQ_EventPublish are not attached. Their exact effects, such as customer account bookings and the MQ event, are not documented here.

Tables used

Invoices · Write Currency · Read Addresses · Read Countries · Read VATs · Read Customers · Read Shops · Read ShipVendor · Read InvoicePackage · Write
SQL object:
dbo.pipiManualCreditCreate
Updated at 2026-10-30