Invoice sending

Maventa delivers invoices as e-invoices through multiple networks — country-specific networks, Peppol, or fallback methods like email and print. Send the invoice to Maventa and let it automatically choose the best delivery route based on the recipient’s business ID, or specify a route manually — for example, email.

For details on available delivery channels in each market, see the country-specific guides. For more information about Peppol, see the Peppol network page.

To send an invoice, you need:

• Sender company account: A company account in Maventa. Invoice sending is enabled by default, but additional services like the print service must be activated separately.
• Invoice XML: An invoice XML file from your system in a supported e-invoice format. Attachments or a custom invoice image can also be included.
• Recipient information: An electronic invoicing address, business ID, email, or postal address for the recipient.

Step 1: Prepare your invoice

Generate and prepare the invoice along with any necessary attachments in your system, then send them to Maventa via the API.

Create the XML file

Create a valid XML file by mapping data from your system into the required XML structure.

XML structures invoice data in a standardised way. Maventa supports a wide range of XML formats and automatically converts invoices between them when needed. See the full list of supported formats and more information about invoicing formats.

Maventa recommends Peppol BIS 3.0, as it is widely supported and well suited for cross-border invoicing. This format fully complies with the European EN16931 (SFS-EN 16931-1:2017) standard. In some cases, it may be more practical to choose a format based on the countries your companies operate in and the type of invoicing you need. For example, in Finland and for B2C invoicing, Finvoice is the recommended format.

The specific format typically does not make a significant difference, as most formats are compatible in terms of core content. Any missing data can be provided as API parameters.

Recipient lookup and routing

To confirm that a recipient can receive e-invoices, perform a lookup before sending. If the recipient cannot receive e-invoices, the invoice can be sent via fallback delivery routes such as email or print. You can handle this lookup yourself or let Maventa do it automatically.

Maventa follows a predefined delivery route order based on the sender’s country. Generally, Maventa first tries delivery through its internal network, then through Peppol or country-specific e-invoicing networks (order varies by country), and finally through fallback routes — email first, then print as the last resort.

You can influence this routing by defining which delivery routes are allowed or restricted, either directly in the XML file or via API metadata.

Automatic lookup and routing

• Matching based on e-invoice address:

If you provide a valid e-invoice address, such as a Peppol IDA Peppol participant identifier consisting of a scheme prefix and company identifier, used to route documents within the Peppol network (e.g., 9925:be000000000b21) or another supported identifier, Maventa looks up the recipient in e-invoice address registries and attempts direct delivery through the identified route. Adding an operator code (e.g., PEPPOL) alongside the e-invoice address forces delivery through that specific route, disabling fallback options even if delivery fails. The operator code can be specified in the API metadata or the invoice XML, depending on the format (note: Peppol BIS 3.0 does not support an operator code field).

• Recipient’s business ID based lookup:

If you don’t know the recipient’s e-invoice address, Maventa attempts to find one using the recipient’s business ID from the invoice data (e.g., VAT number or national business registry number). If a matching e-invoice address is found, Maventa attempts delivery through the identified route.

• Alternative fallback delivery routes:

If no e-invoice address is found, or if delivery to the identified address fails, Maventa can still deliver the invoice through other routes — such as email or print. This is determined by your account configuration, metadata provided in the sending method, or data on the invoice.

Manual lookup

To perform the lookup yourself before sending, use the GET /v1/lookup/receivers method. You can search by company name, business ID (VAT number or national business registry number), or e-invoice address (e.g., OVTFinnish e-invoice address identifier, created by combining prefix '0037' with the Business ID without hyphen, GLNGlobal Location Number — an international identifier for business locations, using Peppol scheme '0088').

API parameters:

• network — PEPPOL for recipients in the Peppol network, INTERNAL for recipients within Maventa’s internal network, EXTERNAL for recipients in external registries (e.g., Finnish or Swedish operator networks), SPROOM for recipients behind Sproom and Nemhandel
• eia — the recipient’s full e-invoice address (EIA)Electronic Invoicing Address — the unique identifier used to route e-invoices to the correct recipient, such as an OVT number or Peppol ID, if known
• bid — the recipient’s business ID, if the e-invoice address is not known
• name — the recipient’s name, if no other identifier is available
• country — the recipient’s ISO country code, to narrow down results

The lookup determines whether the recipient can receive electronic invoices and through which delivery route. It also returns the recipient’s e-invoicing address (e.g., a Peppol participant identifier such as 9925:be000000000b21) and which Peppol document types the recipient supports (INVOICE or CREDIT_NOTE).

https://ax.maventa.com/v1/lookup/receivers?network=PEPPOL,INTERNAL,EXTERNAL&name=3478209-8&country=FI&page=1&per_page=100

[
  {
    "eia": "0216:003734782098",
    "network": "PEPPOL",
    "operator": "PEPPOL",
    "document_types": [
      {
        "document_type": "CREDIT_NOTE",
        "document_identifier": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
        "process_identifier": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
      },
      {
        "document_type": "INVOICE",
        "document_identifier": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
        "process_identifier": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
      }
    ],
    "participant": {
      "name": "Maventa Oy",
      "country": "FI"
    }
  }
]

How to use recipient data on the invoice

Recipient information can be provided in two ways when sending an invoice through Maventa:

• In the XML file – depending on the format, this may even be mandatory (e.g., Peppol BIS 3.0).
• As parameters in the API call – if both XML and API parameters are provided, the API parameters take precedence.

If both a business ID and an Endpoint ID are included in the XML, the Endpoint ID will take priority for routing the invoice. Note that automatic lookup by business ID alone is only supported for certain countries — see automatic lookup and routing for details.

Example: Including e-invoice address (EndpointID) for Peppol BIS 3.0:

<cac:Party>
  <cac:EndpointID schemeID="9930">123456789</cac:EndpointID>
</cac:Party>

Invoice image and attachments

How invoice images (such as PDFs) and other attachments are included depends on the invoice format. They can either be embedded within the XML (e.g., Peppol BIS 3.0) or included as separate files in a ZIP package alongside the XML (e.g., Finvoice 3.0).

Follow the specific requirements of each format to ensure successful processing and delivery. Keep in mind that not all recipients support or display attachments — some may ignore them entirely. While including a PDF can be helpful, it is optional; the XML must always be complete and valid on its own.

Supported file types: pdf (recommended), tif, tiff, jpg, jpeg, png, gif, txt, xml, xls, xsl, xlsx, html, htm, aix, doc, docx, ods, csv.

Embedding in Peppol BIS 3.0 and other UBL-based formats

In Peppol BIS 3.0, attachments must be embedded within the XML file as defined in the specification. Attachments placed outside the XML (e.g., in the ZIP file) are ignored.

ZIP Packaging for other formats

If you are using a format that does not support embedded attachments, include attachments within the same ZIP file as the XML. To ensure Maventa correctly recognises the invoice image, the XML and the invoice image must have the same file name (e.g., 12345.xml and 12345.pdf). Other attachments do not need to match the XML filename.

Fallback for missing invoice image

If no invoice image is included and the delivery route requires one (e.g., print), Maventa automatically generates a visual invoice image from the XML data. The Peppol route does not require an invoice image.

• Example of invoice image (Finland)
• Example of invoice image (Sweden)

File size limits

To ensure reliable delivery and avoid processing issues, follow these size guidelines:

• Maximum size per attachment: 10 MB
• Maximum total package size: 100 MB

Best practice: Keep attachments as small as possible for better performance and delivery success.

Filenaming requirements

All files sent through the service must follow these naming rules:

• File names may only include letters (A–Z), numbers (0–9), periods (.) and underscores (_)
• Special characters are not allowed
• The file name must not exceed 50 characters in length

Validate before sending

Validating your invoice XML before sending is optional. Maventa validates all invoices automatically during the sending process. If you already have a validation process or are confident your XML is valid, skip this step. Pre-send validation simply helps catch issues earlier.

Call POST /v1/validate to validate your invoice XML. Read more about validation.

Step 2: Send your invoice

All Maventa company accounts have invoice sending enabled by default. Before sending, make sure your invoice is properly constructed and, ideally, validated.

To send an invoice through Maventa, send the XML file along with required parameters using POST /v1/invoices.

{
  "format": "PEPPOLBIS3",
  "recipient_eia": "0216:003734782098",
  "recipient_operator": "PEPPOL",
  "recipient_email": "fallback@example.com",
  "disabled_routes": ["print"],
  "file": "<base64-encoded invoice XML>"
}

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "PROCESSING",
  "number": "INV-2026-001",
  "recipient": {
    "name": "Maventa Oy",
    "bid": "3478209-8",
    "eia": "0216:003734782098"
  },
  "destination": "PEPPOL"
}

The file parameter contains the base64-encoded invoice XML. If you are sending a ZIP package (XML with attachments), base64-encode the entire ZIP file. After a successful send, Maventa responds with a UUID (invoice ID), which should be saved in your system to track delivery status and updates.

Key API parameters

• Recipient details — Provide the recipient’s e-invoicing address (recipient_eia) and/or operator (recipient_operator).
• Email fallback — Add the recipient’s email address using the recipient_email parameter for fallback delivery if e-invoicing is not possible.
• Country-specific invoicing fields — Some parameters are specific to certain countries, for example fields required for B2C invoicing in Finland or Norway.
• Print settings — Define invoice-specific print preferences that override the company-level defaults. Read more about print service.
• Language settings — Use the lang parameter to define the language of the generated PDF and email content. Supported languages: FI, SE, NO, NL, DK, and EN.
• Custom invoice ID — Use the uuid parameter to specify your own invoice ID for tracking purposes. The value must be a valid UUID. If not provided, Maventa generates one automatically. Store this ID in your system to monitor delivery status and updates.
• Prevent routing — The prevent_routing setting marks an invoice as SENT without actually delivering it. This is typically used to manually create an assignment for Maventa’s reminder or debt collection services without sending the invoice itself.
• Email settings — Use email_settings[xml_format] to force email delivery and include the XML attachment in the specified format. Read more about email invoicing.

Controlling delivery routes

To block certain delivery routes, use the disabled_routes parameter. This gives you control over which routes (einvoice, email, print) are allowed or blocked for each invoice.

Keep in mind:

• Adding an operator code (e.g., PEPPOL) alongside the e-invoice address forces delivery through that specific network, disabling fallback options even if delivery fails.
• If recipient details are provided both in the API request and in the XML file, the API parameters override the values in the XML.
• Store the invoice ID for tracking purposes.

Preventing duplicate invoices

Maventa offers two mechanisms to prevent sending the same invoice twice:

• Custom UUID — Use the uuid parameter in POST /v1/invoices to assign your own invoice ID. If an invoice with the same UUID already exists, the API rejects the duplicate.

• Duplicate invoice number prevention — Enable the stop_duplicate_numbers setting using PATCH /v1/company/settings (set stop_duplicate_numbers to true). When enabled, Maventa rejects any invoice with the same invoice number that was sent within the past 7 days. The API returns a DUPLICATE INVOICE NUMBER error in this case. After 7 days, the same invoice number can be used again.

Cancelling a sent invoice

A sent or delivered invoice cannot be cancelled through Maventa. Once an invoice has been sent, it has already been handed over to the recipient’s operator or delivery channel.

If you need to cancel an invoice after it has been sent, the correct approach is to send a credit note to the recipient. This is the standard and officially recognised way to reverse an invoice. Alternatively, the sender can contact the recipient directly to arrange cancellation outside the invoicing system.

Step 3: Follow up and handle errors

After sending the invoice and storing its invoice ID, monitor its delivery progress. Maventa recommends webhooks for real-time tracking. As a backup, you can also poll the API to check invoice status.

Register for webhook notifications for sent invoices

Register a webhook for sent invoice events using POST /v1/company/notifications:

{
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.DELIVERY_CONFIRMED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}

{
  "id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.DELIVERED",
    "DOCUMENTS.INVOICE.DELIVERY_CONFIRMED",
    "DOCUMENTS.INVOICE.FAILED"
  ]
}

Maventa calls the specified endpoint with a payload like this when an invoice is delivered:

{
  "event":"DOCUMENTS.INVOICE.DELIVERED",
  "company_id":"xxxxe05d-42f0-4e76-acd6-968ab455xxxx",
  "event_timestamp":"2019-11-23T12:03:48+02:00",
  "event_data": {
    "invoice_id":"xxxx8354-5998-495b-8675-67bf05dexxxx",
    "invoice_number":"1003",
    "destination":"PEPPOL",
    "recipient_name":"Recipient",
    "recipient_bid":"933640000"
  }
}

Maventa calls the specified endpoint with a payload like this when invoice sending fails:

{
  "event":"DOCUMENTS.INVOICE.FAILED",
  "company_id":"xxxxe05d-42f0-4e76-acd6-968ab455xxxx",
  "event_timestamp":"2019-11-23T12:03:48+02:00",
  "event_data": {
    "invoice_id":"xxxx8354-5998-495b-8675-67bf05dexxxx",
    "invoice_number":"1001",
    "destination":"PEPPOL",
    "recipient_name":"Recipient",
    "recipient_bid":"933640000",
    "error_message": "Error that happened"
  }
}

Update your database for the invoice ID in question based on the event. Refer to the webhook doc for more details.

Keep in mind:

• An invoice marked as DELIVERED can still fail afterwards — for example, if an email bounces due to a full inbox or an invalid address.
• If you receive DELIVERY_CONFIRMED, the invoice is considered fully delivered, and the status should not change to FAILED.
• You can safely show both statuses to your customers — just note that DELIVERED alone does not always guarantee final delivery success.
• Not all routes support DELIVERY_CONFIRMED.

Polling for the status

If webhooks are not an option, check invoice status by polling the API. Polling can also serve as a backup in case webhook delivery fails.

Use GET /v1/invoices/{id} to poll an individual invoice by its invoice ID (UUID).

Recommended polling frequency:

• While the invoice is still PENDING: poll every 1 hour.
• After the invoice reaches SENT or DELIVERED status: poll once per day for up to 1 month, or until payment is received.
• As a backup for webhooks: poll once a day or a few times per week.

The SENT status does not guarantee successful delivery. An invoice can still fail after this point, so keep polling until the final status is confirmed.

Delivery times

Invoices are usually sent within about 10 minutes, moving from pending to sent/delivered state. At the turn of the month or during high-traffic periods, queues can be longer and delivery may take up to a few hours.

In some cases, especially with Peppol invoices, temporary issues caused by other access points can delay delivery. When this happens, the invoice may remain in pending while Maventa checks, resends, or takes other steps to ensure successful delivery.

Invoices do not remain stuck in pending without notice. Maventa’s internal alerting system monitors all pending invoices, so everything is eventually processed — sometimes with a short delay if manual action or coordination with the receiving access point is needed.

Invoice statuses

The REST API uses the following statuses when filtering invoices with GET /v1/invoices:

• PENDING — The invoice is queued and waiting to be sent.
• DELIVERED — The invoice has been successfully handed over to the recipient’s delivery channel.
• FAILED — All available delivery routes were attempted, but the invoice could not be delivered.

The invoice lifecycle also includes these additional statuses:

• DELIVERY_CONFIRMED — The delivery channel has confirmed receipt or completion of delivery. Not all routes support this.
• ERROR — Same as FAILED. The invoice could not be delivered.

When the invoice fails

If the invoice status is FAILED (or ERROR), all available delivery routes were attempted but the invoice could not be delivered.

How to resolve the issue depends on the root cause:

• Incorrect address — Correct the address and re-route the invoice.
• Routing errors — If the issue relates to routing (e.g., delivery channel unavailable, no routes found), re-route the invoice to another channel if possible.
• Validation errors — If the invoice content is invalid (e.g., missing required fields or schema issues), correct the XML and resend the invoice as a new invoice.

Maventa offers a setting that enables companies to receive delivery failure notifications via email. This helps identify and address issues promptly. Maventa recommends that your system notifies the user whenever action is required.

Re-routing an invoice

To redirect an invoice to a different address or delivery route, use one of these API endpoints:

• PUT /v1/invoices/{id}/reroute/einvoice - for e-invoice delivery
• PUT /v1/invoices/{id}/reroute/email - for email delivery
• PUT /v1/invoices/{id}/reroute/print - for print delivery

Testing invoice sending

Before going to production, test your invoice sending integration in the Maventa testing environment. For general setup instructions, API keys, and environment details, see the getting started guide.

To test internal sending between Maventa accounts, create two company accounts in the testing environment and send invoices from one to the other. Internal sends between Maventa accounts work the same way in testing as in production.

To test sending via Peppol, the testing environment is connected to the Peppol test network. You can register one of your test accounts as a Peppol receiver — the registration is created in the Peppol test environment. Then send an invoice to that account from another test account to verify the full Peppol flow end to end. You can also use Peppol’s public test endpoints to send test invoices without needing a real recipient.