Invoice Response

What is an invoice response?

An invoice response is a message between buyer and seller that provides an efficient way to communicate the processing status of a received invoice in the Peppol network.

For example, the buyer can inform the seller whether an invoice has been rejected, is under query, has been approved, or has been paid.

For detailed use cases and the full specification, see the Peppol BIS Invoice Response 3.2 documentation.

Setting up invoice responses

For a company sending invoices (seller)

When a company sends invoices, it is the seller and therefore the receiver of invoice responses from the buyer. Follow these steps to enable receiving.

Step 1: Register for invoice response receiving

Register a receiving profile for invoice responses in the Peppol network.

Call POST /v1/company/profiles with the following parameters:

• profile: INVOICE_RESPONSE
• network: PEPPOL

Once the profile is created, use GET /v1/company/profiles to verify that the profile has been activated for the PEPPOL network.

Step 2: Integrate with the documents endpoint

Incoming invoice responses are received through the documents endpoint. See the document receiving section for details on listing and downloading received documents.

Step 3: Process the received invoice response

Parse the received XML and update your system accordingly. For details about the content and structure of invoice responses, see the Peppol documentation.

For a company receiving invoices (buyer)

When a company receives invoices, it is the buyer and therefore the sender of invoice responses to the seller. Follow these steps to enable sending.

Step 1: Integrate to receive invoices

Set up invoice receiving so you have invoices to respond to.

Step 2: Check if the seller supports invoice responses

Before sending an invoice response, check whether the seller can handle invoice response documents. Use the GET /v1/lookup/receivers endpoint with the seller’s identifier from the received invoice.

In a Peppol BIS 3.0 document, the seller’s identifier is in the EndpointID element:

<cbc:ID>567</cbc:ID>
  ...
  <cac:AccountingSupplierParty>
    <cac:Party>
      <cbc:EndpointID schemeID="0216">003751734872004</cbc:EndpointID>
      ...
    </cac:Party>
  </cac:AccountingSupplierParty>

The lookup requires three parameters:

• network — set to PEPPOL
• document_type — set to INVOICE_RESPONSE
• eia — the seller’s identifier in the format 0216:003751734872004 (taken from the received invoice)

curl -X 'GET' \
  'https://ax-stage.maventa.com/v1/lookup/receivers?network=PEPPOL&eia=0216%3A003751734872004&document_type=INVOICE_RESPONSE' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer TOKEN'

[
  {
    "eia": "0216:003751734872004",
    "network": "PEPPOL",
    "operator": "PEPPOL",
    "document_types": [
      {
        "document_type": "INVOICE_RESPONSE",
        "document_identifier": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:invoice_response:3::2.1",
        "process_identifier": "urn:fdc:peppol.eu:poacc:bis:invoice_response:3"
      },
      ...
    ],
    "participant": {
      "name": "Seller",
      "country": "FI"
    }
  }
]

If the seller is registered for invoice responses, the endpoint returns matching entries. If not, the response is an empty array.

Step 3: Generate and send an invoice response

Create a compliant invoice response XML document. For details about the business content and structure, see the Peppol BIS Invoice Response specification.

Below is an example invoice response payload that acknowledges receipt of invoice 567 from seller 0216:003751734872004:

<?xml version="1.0" encoding="UTF-8"?>

<ApplicationResponse xmlns="urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <cbc:CustomizationID>urn:fdc:peppol.eu:poacc:trns:invoice_response:3</cbc:CustomizationID>
  <cbc:ProfileID>urn:fdc:peppol.eu:poacc:bis:invoice_response:3</cbc:ProfileID>
  <cbc:ID>1</cbc:ID>
  <cbc:IssueDate>2024-01-01</cbc:IssueDate>
  <cac:SenderParty>
    <cbc:EndpointID schemeID="0216">003751734872001</cbc:EndpointID>
    <cac:PartyLegalEntity>
      <cbc:RegistrationName>Buyer</cbc:RegistrationName>
    </cac:PartyLegalEntity>
  </cac:SenderParty>
  <cac:ReceiverParty>
    <cbc:EndpointID schemeID="0216">003751734872004</cbc:EndpointID>
    <cac:PartyLegalEntity>
      <cbc:RegistrationName>Seller</cbc:RegistrationName>
    </cac:PartyLegalEntity>
  </cac:ReceiverParty>
  <cac:DocumentResponse>
    <cac:Response>
      <cbc:ResponseCode listID="UNCL4343OpSubset">AB</cbc:ResponseCode>
    </cac:Response>
    <cac:DocumentReference>
      <!-- Reference to the original received invoice -->
      <cbc:ID>567</cbc:ID>
      <cbc:DocumentTypeCode listID="UNCL1001">380</cbc:DocumentTypeCode>
    </cac:DocumentReference>
  </cac:DocumentResponse>
</ApplicationResponse>

Send the invoice response XML via the POST /v1/documents endpoint:

curl -X 'POST' \
  'https://ax-stage.maventa.com/v1/documents' \
  -H 'accept: application/json' \
  -H 'content-type: multipart/form-data' \
  -F 'file=@response.xml;type=text/xml' \
  -F 'recipient_eia=0126:003751734872004' \
  -F 'recipient_operator=PEPPOL'

Response:

{
  "id": "e6c1e92b-ceba-4155-89fd-072e7ba6148f",
  "type": "INVOICE_RESPONSE"
  ...
}

Response codes

Each invoice response carries a single status code that communicates the current processing state of the invoice. The code is set in the ResponseCode element using the UNCL4343 code list subset.

Status codes follow a general progression: AB → IP → UQ → CA/RE/AP → PD. Not all statuses need to be used — for example, a buyer may go directly from AB to AP. The statuses RE and PD are final; no further responses should be sent after these.

References

• BIS Invoice Response 3.2 specification