Skip to content

Moloni

Moloni provider — identifier moloni. Issuing invoice-receipts and credit notes, and downloading their PDFs, has been verified against a real Moloni account.

Setting up Moloni

In Moloni

  1. In Moloni's developer area, create an application. Note its Developer ID (client_id) and Client secret.
  2. Register the plugin's redirect URI on that application. It is shown (with a Copy button) on the plugin's settings page and is the same for every event and organizer: https://<your pretix domain>/control/ptinvoicing/moloni/callback/.
  3. In the company you'll invoice from, make sure you have a document series for invoice-receipts and a separate one for credit notes (a Moloni series is bound to one document type), plus at least one payment method and one maturity date ("Pronto pagamento").

In pretix

Open the event's Settings → Invoicing (PT) and click the Moloni card. To set Moloni up once for all of an organizer's events, do the same on the organizer's Settings → Invoicing (PT) instead; see One connection for every event.

The Moloni section once connected: connection state, redirect URI, developer ID and client secret, then the dropdowns from the company to the payment method

  1. Fill in the Developer ID (client_id) and Client secret.
  2. Press Connect to Moloni. You're sent to Moloni to authorize the application, then brought back to this page. Whatever you had typed is saved on the way; there's no need to save first. Once back, the panel shows Connected with Reconnect to Moloni and Disconnect buttons.
  3. Pick the Company. With several companies in the account you must pick one explicitly; each option shows the name and NIF. The remaining dropdowns load for that company.
  4. Pick the Document set for invoice-receipts and the Credit note document set. They must be different series, the latter created for the Credit Note document type.
  5. Pick the VAT rate pretix charges on the tickets, and an Exemption reason if any ticket is sold at 0%. See Taxes.
  6. Pick the default Payment method, a Maturity date, and the Product type and Unit that the plugin's catalog products are created with. See Products.

    The Moloni section's dropdowns, from the document sets to the maturity date

  7. Optionally map each pretix payment method to a Moloni one in the Payment methods table. See Payment methods.

    The end of the Moloni section on an event's page: unit, reference limit, maturity date and the payment methods table, with the Save button

  8. Press Save. Until you do, the section says Not in use yet and nothing is issued.

The connection

Connect to Moloni uses Moloni's authorization-code flow: no Moloni password is stored, only the access and refresh tokens. The refresh token expires after 14 days without use, so the plugin refreshes every connection once a day, and a quiet event never loses it.

If Moloni refuses a refresh, the connection is marked expired: the settings page says so, the order panels warn that nothing can be issued, and the event's contact e-mail (pretix Settings → General) gets a message with a link to reconnect. Press Reconnect to Moloni.

Disconnect asks for confirmation first, since without a connection no document can be issued for the event.

Username and password

Still accepted as an alternative to Connect to Moloni, and hidden while connected. With them set, an expired connection logs in again by itself instead of waiting for you to reconnect.

One connection for every event

Press Connect to Moloni on the organizer's Settings → Invoicing (PT) and every event of that organizer issues through that connection, with the company, series and other settings saved there. Nothing has to be connected per event; see Organizer-wide settings for how events inherit.

On such an event's settings page:

An event's Moloni section reading "Connected through the organizer's settings", with the "Connect this event on its own" button

  • the panel reads Connected through the organizer's settings, and there is no Disconnect button, since the connection isn't the event's to remove;
  • Connect this event on its own gives the event a connection of its own (another Moloni account, for example). The organizer's connection, and every other event, is left untouched. Disconnect on that event later removes only its own connection, and it uses the organizer's again;
  • the payment methods table is still filled in per event.

A shared connection is refreshed once a day for the organizer, not once per event. If it expires, each event's page says that the organizer's connection has expired and links to the organizer's page, where Reconnect to Moloni restores it for all of them. The warning e-mail goes to the contact e-mail of the events using it, once per address.

Settings

Most fields turn into dropdowns filled from your Moloni account once you're connected. The company-specific ones load after you pick a Company.

Setting Required Description
Developer ID (client_id) yes From Moloni's developer area.
Client secret yes From Moloni's developer area.
Moloni username / password no Only without Connect to Moloni; see above.
Company yes With several companies in the account you must pick one explicitly. Each option shows the name and NIF.
Document set yes Series used for invoice-receipts.
Credit note document set yes A series created for the Credit Note document type. It can't be the invoice-receipt's series.
VAT rate for taxed tickets Must be the same rate pretix charges; see Taxes.
Exemption reason for 0% tickets Moloni's exemption codes, e.g. M07 (Artigo 9.º do CIVA).
Payment method yes Invoice-receipts always carry a payment; this is the method it's recorded under when a pretix payment method has no mapping of its own.
Product type yes Service (default), Product or Other: what catalog products are created as, unless the product's own page says otherwise. See Products.
Unit yes The products' unit of measure.
Reference limit no How long a product reference may be in Moloni, prefix included. Defaults to 30, Moloni's maximum; lower it if your account allows fewer.
Maturity date yes Set on each new Moloni customer, e.g. "Pronto pagamento".
Payment methods (table) no One row per payment method the event accepts; see Payment methods. Not shown on an organizer's page.

Payment methods

Moloni records a payment on every invoice-receipt. The Payment methods table lists each payment method the event accepts (Multibanco, MB WAY, bank transfer, box office…) and lets you pick the Moloni payment method it is recorded under. A row left at default uses the Payment method setting above.

An order paid through several methods gets one payment entry per method, with its amount. An order marked as paid by hand in the Control panel is recorded under the method of its latest other payment attempt (a Multibanco reference that was paid but never confirmed automatically counts as Multibanco).

Products

Moloni only invoices products from its catalog, so each pretix product gets one, created automatically on its first sale and reused from then on. Moloni's sales reports therefore stay per ticket type. Each line on the document still shows the pretix product name and the price actually paid.

Reference. A catalog product is found by its reference: the Product reference prefix from the general settings (pretix- by default) followed by the product's own reference.

  • Without one of its own, a product's reference is item-<id>, giving pretix-item-<id>. Each fee type (payment fee, shipping…) gets a product too, pretix-fee-<type>.
  • To choose it, open the product in pretix: its page has an Invoicing (PT) tab with a Product reference field. VIP there makes the catalog reference pretix-VIP. Two products of one event can't share a reference, and the shapes item-<number> and fee-… are reserved.

    The Invoicing (PT) tab of a pretix product's page, with the Product reference and Type (Moloni) fields

  • Prefix and reference together may be at most 30 characters (the Reference limit setting). The settings page shows how many are left for the reference as you type the prefix, and refuses a prefix that leaves fewer than 12. A reference that is too long stops issuance with an error naming the product, before anything is created in Moloni.

  • A reference only matters until the product exists in Moloni. Changing it, or the prefix, later makes the next sale create a new catalog product; the old one stays in Moloni.

Category. Products are created under Pretix > event name, a category tree the plugin creates as needed, so the catalog reads by event. A product that already exists stays in the category it is in.

Type and unit. From the Product type and Unit settings. The product's Invoicing (PT) tab has a Type (Moloni) field to create that one product as something else (Product, Service, Other or Taxes/fees).

Events that share a Moloni company share nothing by default, since pretix product ids are unique across the installation. Give two products in different events the same reference and prefix, and they are invoiced as one catalog product; that is yours to avoid, or to use.

Taxes

Each line follows the VAT pretix actually charged on it:

  • Taxed line — sent with the configured VAT rate. If that rate isn't the one pretix charged, issuance stops with VAT mismatch: … before anything is created in Moloni. Otherwise the document would be for a different amount than the buyer paid.
  • 0% line — sent without tax, with the Exemption reason instead. Moloni requires one, so an order with 0% lines and no exemption reason set stops with an explicit error.

Unit prices on the PDF

Moloni stores unit prices to 5 decimals and prints the gross unit price from them. A tax-inclusive €35.00 at 23% therefore prints as 34,99999 at best, because 35 / 1.23 never ends. The incidence, VAT and total are right (28,46 + 6,54 = 35,00, the same split pretix's own invoice shows). Only prices whose net is whole cents (pretix's "price includes tax" off) print clean.

Customers

A buyer with a NIF is matched to an existing Moloni customer when exactly one has that NIF. If several do, issuance stops (Moloni has N customers with tax number X. Merge them in Moloni, then retry.). Otherwise a customer is created from the order's invoice address. Buyers without a NIF share one final-consumer customer (999999990), matched by name.

A reused customer is never overwritten. When the order's address differs from the one Moloni has on file, the document is issued with an alternate address instead, so the PDF shows the address the buyer gave on this order. Countries are looked up in Moloni by ISO code.

Duplicate protection and retries

Moloni has no field it rejects duplicates on, so a request that timed out may or may not have created a document. The plugin therefore asks Moloni first: before every attempt it looks for a closed document carrying the order's reference (pretix-<event>-<order code>, stored in Moloni's our reference), and if there is one, it is linked to the order instead of issuing another.

That makes retries safe. A network failure (timeout, Moloni unreachable) is retried automatically, up to three times a couple of minutes apart; the row reads retrying automatically in a few minutes meanwhile, and gave up after several attempts if every retry failed. Pressing Retry by hand goes through the same lookup.

A rejection (invalid data, VAT mismatch, expired connection) is never retried automatically: fix the cause, then press Retry.

Credit notes

Built from the original document's line items and associated to it, crediting it in full. They use the Credit note document set.

Documents and numbers

The number shown in pretix (e.g. FR M2026/20, NC M2026/6) is read back from Moloni right after issuance: the document type's SAF-T code, the series name and the number.