# Upload supplier e-invoices

<FeatureStatus feature="EInvoiceImport" />

Some suppliers send no cost export, only an invoice. When that invoice is a structured e-invoice, a
custom provider can read it: you create the provider with the **E-invoices** upload format, upload
each invoice of that supplier, and every invoice line appears in Cost Reports under the provider's name,
beside the rest of your cost.

## How Costfluent reads an invoice

Costfluent reads the invoice's structured data, not its printed page. It reads:

- XRechnung, in UBL or CII syntax.
- ZUGFeRD 2.x and Factur-X, in the profiles BASIC, EN 16931 and EXTENDED.

Each can be uploaded as its XML file or as the PDF/A-3 that embeds the XML. Peppol BIS Billing is
not among these formats, although it shares the UBL syntax.

Each invoice line becomes cost at its net amount (BT-131), in the invoice's currency. Costfluent
spreads it over the period the line bills for: the line's own period, else the invoice's period,
else the delivery date, else the issue date. An allowance on the whole invoice becomes a discount,
and a charge on the whole invoice becomes a fee.

- A commercial invoice (type 380) or a partial invoice (326) adds its lines to your cost.
- A credit note (381) nets out against it.
- A corrected invoice (384) replaces the invoice it references, which must have been uploaded to
  the same provider first.

Several invoices of one supplier in the same month all count. Unlike a CSV upload, an invoice
replaces no days of an earlier upload.

### VAT

VAT is never counted as cost. Each upload shows the invoice's net total, its VAT per category and
its gross total. An invoice under reverse charge (VAT category AE) is labelled as such, and its net
amount stays the cost.

:::note
Costfluent counts the net amount for every organization. Counting VAT as cost, for an organization
that cannot deduct input VAT, is not supported yet.
:::

### Not an invoice archive

:::caution
Costfluent does not check an invoice against the legal requirements for invoices, and it does not
archive invoices as the retention rules for accounting records require (in Germany, the GoBD). Keep
every invoice in the archive your accounting uses. Costfluent keeps the extracted XML only as the
source of its upload.
:::

## Prerequisites

- The **Manage integrations** capability, which owners and integration owners hold, to create the
  provider and to upload or delete invoices. Anyone with **View integrations** can see the uploads.
- A supplier that sends its invoices in one of the formats above, and whose cost Costfluent does not
  already collect ([Avoid double counting](#avoid-double-counting)).

## Connect

### Create the provider

<Stepper>

1. Open **Settings**, then **Integrations**, and under **Upload files** select **Supplier e-invoices**.
2. Select **New e-invoice provider**, on the **Manage** or the **Connect** tab. The
   **New custom provider** dialog opens with **E-invoices** selected under **Upload format**.
3. Enter a **Display name**, such as the supplier's name, and optionally a **Description**, then
   select **Create provider**.

</Stepper>

The provider's page opens. A provider holds one supplier: the seller of its first invoice. Create
one provider for each supplier. The same dialog on the **Custom provider** page opens with
**FOCUS CSV files** selected instead. As the dialog says, the format cannot be changed once the
provider has an upload.

### Upload an invoice

<Stepper>

1. On the provider's page, under **Uploads**, select **Choose invoice** and pick one invoice, as
   `.xml` or `.pdf`.
2. Select **Upload**.

</Stepper>

Each upload holds one invoice. It goes through the same statuses as a CSV upload
([Upload statuses](/connect/custom-provider#upload-statuses)). Its row shows:

- **Invoice**: the invoice number, the seller and the file name, marked **Credit note** or
  **Corrected invoice** for those types and **Reverse charge** for an invoice under reverse charge.
- **Period**: the period the invoice's cost covers, filled once the upload is processed.
- **Net**, **VAT** and **Gross**: the invoice's net total, its VAT with the amount per category and
  rate (such as `S 19%` or `AE 0%`), and its gross total. A credit note's amounts appear negative,
  as the cost it nets out.

**Which invoices are read**, under the card's description, links to this page.

### Avoid double counting

Do not upload an invoice of a supplier whose cost Costfluent already collects through a connection.
That bill would count twice.

## Invoice address

Instead of uploading each invoice, you can forward the mail that brings it. Each organization has
one invoice address, shown on the **Manage** tab of **Supplier e-invoices** under
**Invoice address**. The organization roles Owner and Integration Owner create it with **Create address**.

A forwarded mail becomes an upload within minutes when all of these hold:

- it carries an EN 16931 invoice: an XML file, or a PDF with embedded ZUGFeRD or Factur-X data;
- its DKIM signature from the sender's own domain is intact;
- its sender is a member of your organization or an allowed sender;
- exactly one e-invoice provider already holds an upload of that seller.

Anything else is held with its reason, never imported by guess. Costfluent never replies to a
forwarded mail.

### Forward your mail

Set your mailbox to forward invoice mail to the address. Gmail and Zoho Mail first send a
confirmation code to the address; it shows under **Held** with the provider's subject, where you
read the code. In Microsoft 365, an administrator may have to allow automatic forwarding to an
external address.

An automatic forward keeps the supplier's signature. A forward you send by hand is signed by your
own domain instead, so it is imported when you are a member, and the invoice inside still names
the supplier.

### Allowed senders

Under **Allowed senders**, add the exact addresses, or `@domain` entries, whose invoices are
imported beside your members'. A held mail from a supplier you trust offers
**Allow sender and import**, which adds its sender and imports the invoice.

### Held mail

**Held** lists each forwarded mail that was not imported, with its sender, subject, attachments
and reason. Its content is never shown; the original stays in your mailbox.

- **No e-invoice found**: no attachment is a structured invoice.
- **Sender not verified**: no valid signature from the sender's domain.
- **Sender not allowed**: the sender is neither a member nor an allowed sender.
- **Unknown supplier**: no e-invoice provider, or more than one, holds an upload of this seller.
  **Import to provider** imports it to the provider you choose.
- **Import refused**: the invoice was read but refused, with the reason an upload would show.
- **Over a limit**: the mail is larger than 25 MiB, or has too many parts or nested messages.
- **Processing failed**: the mail could not be read; forward it again or upload the invoice.

Held invoices can be imported for 30 days. A held mail is listed for 90 days.

### Replace the address

**Replace address** gives the organization a new address. The old one stops working at once, so
change your forwarding to the new one.

## Data and freshness

An invoice upload is processed in turn with the other uploads to custom providers
([Data and freshness](/connect/custom-provider#data-and-freshness)).

The same file uploaded again returns the first upload and imports nothing twice; the console says
the invoice was uploaded before, unchanged, and names its number when that upload is on the page
shown. A different
document with an invoice number the provider already holds is refused.

### Limits

- One file per upload, of at most 20 MiB.
- At most 10,000 lines per invoice.

## Reporting dimensions

What each group-by dimension of a [cost report](/cost-reports/explore) holds for an invoice line.

| Dimension | For an invoice line |
|---|---|
| **Seller** | The custom provider's name |
| **Service** | The invoice line's item name |

No supplier-specific mapping is available yet, so the service is the item name exactly as the
invoice states it.

## Use the Public API

A token holding **Manage integrations** can do the same through the Public API, as the
[API reference](/api) describes:

1. `POST /v1/providers` with `key` set to `custom`, a `displayName`, empty `credentials` and
   `settings` holding `upload_format` set to `einvoice` creates the provider. Without that setting,
   the provider takes FOCUS CSV.
2. `POST /v1/custom-providers/{providerId}/uploads` takes one invoice in a multipart field named
   `file`. The same file again answers with the first upload; a different document with an invoice
   number the provider already holds answers `409`.
3. `GET /v1/custom-providers/{providerId}/uploads` lists the uploads, and
   `DELETE /v1/custom-providers/{providerId}/uploads/{uploadId}` deletes one.

## Update or disconnect

Delete an upload from its row under **Uploads**. Only that invoice's lines leave your cost; the
provider's other invoices stay. Removing the provider with **Remove connection** in its row's menu on
the **Manage** tab removes all of its cost
([Remove a connection](/connect/manage-connections#remove-a-connection)).

## Troubleshooting

Costfluent refuses an invoice it cannot read completely, imports none of it, and names the reason.
In the console the refusal shows a heading with the server's reason, in English, beneath it:
**This provider already has another document with this number** for an invoice number already
taken, **This provider cannot take this invoice** for an invoice from another seller or a corrected
invoice whose original is missing, and **The invoice could not be read** for the other reasons
below.

- **The invoice has no lines.** The ZUGFeRD and Factur-X profiles MINIMUM and BASIC WL carry no
  invoice lines. Ask the supplier for BASIC, EN 16931, EXTENDED or XRechnung.
- **The format is not read.** ZUGFeRD 1.0 is not read, and neither is a file that contains a DOCTYPE.
- **The PDF holds no invoice data.** Costfluent reads only the XML a PDF embeds; it does not
  recognise the text of a scanned or printed invoice.
- **The upload is too large.** It holds more than one file, the file is over 20 MiB, or the invoice
  has more than 10,000 lines.
- **The invoice type is not read.** Costfluent reads types 380, 326, 384 and 381; a self-billed
  invoice (389) or any other type is refused.
- **The invoice's sums do not add up.** Its own totals disagree with its lines. Ask the supplier for
  a corrected invoice.
- **The invoice comes from another seller.** The provider holds the supplier of its first invoice.
  Create a provider for the other supplier.
- **The corrected invoice's original is missing.** Upload the invoice it references to the same
  provider first.
- **The invoice number is already taken, answered with `409` in the Public API.** The provider holds
  a different document with the same number. Delete the upload that is wrong, then upload the right
  one.
- **The upload format cannot be changed.** The provider already has an upload. Create a new provider
  with the format you need.

## Related

- [Upload cost to a custom provider](/connect/custom-provider)
- [Manage connections](/connect/manage-connections)
- [Currency](/currency)
- [Explore cost data](/cost-reports/explore)
