The Peppol Business Interoperability Specification, “BIS” from here on after, has been developed by the OpenPeppol AISBL Post Award Coordinating Community and is published as part of the Peppol specifications.

Statement of copyright

This Peppol Business Interoperability Specification (BIS) document is based on the CEN CWA prepared by the BII workshop specified in the introduction below. The original CEN CWA document contains the following copyright notice which still applies:

© 2012 CEN All rights of exploitation in any form and by any means reserved worldwide for CEN national Members.

The CEN CWA documents and profiles prepared by the BII workshop are not specific to a business area. Subject to agreement with CEN, customizations have been made by Peppol to establish the Peppol BIS, detailing and adding further guidance on the use of BII profiles.

OpenPeppol AISBL holds the copyright in the customizations made to the original document. The customizations appear from the corresponding conformance statement which is attached to this document. For the purpose of national implementations, customizations covered by the conformance statement may be further refined and detailed by Peppol Authorities and/or other entities authorized by OpenPeppol AISBL, provided that interoperability with Peppol BIS is ensured. This Peppol BIS document may not be modified, re-distributed, sold or repackaged in any other way without the prior consent of CEN and/or OpenPeppol AISBL.

Link to main site of documentation

1. Introduction to openPeppol and BIS

This BIS is a result of work within OpenPeppol and is published as part of the Peppol specifications.

This Peppol BIS provides a set of specifications for implementing a Peppol business process. The document is concerned with clarifying requirements for ensuring interoperability of pan-European Public eProcurement and provides guidelines for supporting these requirements and how to implement them. This Peppol BIS is based on the CEN WS/BII Profile “BII Profile 42 Order Agreement CWA 17029-124” CEN WS/BII 3.

The purpose of this document is to describe a common format for the order agreement in the European market, and to facilitate an efficient implementation and increased use of electronic collaboration regarding the ordering process based on this format.

BII relationship

1.1. Audience

The audience for this document is organizations wishing to be Peppol enabled for exchanging electronic business documents, and/or their ICT-suppliers.

These organizations may be:

  • Service providers

  • Contracting Authorities

  • Economic Operators

  • Software Developers

More specifically it is addressed towards the following roles:

  • ICT Architects

  • ICT Developers

  • Business Experts

For further information, please see Peppol BIS common text and introduction.

2. Principles and prerequisites

This chapter describes the principles and assumptions that underlie the use of Peppol Order Agreement. It is based on the CEN WS/BII 42 Order Agreement.

This profile identifies, explains and justifies the business requirements for the Order agreement process. It provides syntax bindings to UBL 2.1 (Universal Business Language). It also includes a syntax implementation guide.

The order agreement profile describes processes where the buyer, after purchasing items/services, receives a message with information documenting the purchase.

2.1. Prerequisites

The following are prerequisites for this BIS:

  1. A buyer has purchased goods or services from the seller by any means.

  2. The seller has to be registered in the buyer system with information as contact information and identifiers used for other BIS transaction e.g. BIS order and invoice (GLN, Organization number…)

2.2. Scope

The intended scope for this BIS includes business-to-government (B2G) and business-to-business (B2B) relationships. Although the BIS is a basis for an EDI agreement between two parties, it does not address all business level details of such an agreement/contract.

The order agreement represents the combined information of an order and an order confirmation, i.e. it represents an agreement entered upon by seller and buyer. The transaction, specified in this BIS is intended to be exchanged between the seller’s order management system and the of buyer’s purchasing system so that their respective systems get syncronised with regard to the information on the purchase.

The different uses of this BIS are described in Process and typical use cases.

This is an auxiliary BIS intended to complement the primary ordering BISs, such as Peppol BIS 28A. It allows the buyer to have information from less formalized purchase processes conveniently fed into the procurement system, thereby giving control over corresponding payments and better statistics. By opening for order agreement transactions, it is very important that the buyer’s system can verify that the seller is allowed to send an order agreement and that the process is described in the contract between seller and buyer to prevent fraud and to secure good quality in the transaction.

2.3. Goals and Objectives

The following main business goals to be gained by implementing a BII Order agreement profile are the following and apply to this BIS.

Table 1. Main business goals
ID Description

G-42-001

The profile enables buyers to receive real time information on the contracted products/services, resulting in correct and up to date information, such as price and availability based on a contract.

G-42-002

The effort to distribute catalogue information can be substantially reduced for sellers with large catalogues. It does not even presume standardized catalogues.

G-42-003

The profile enables the buyer to create an order in the seller’s web shop.

G-42-004

The profile enables the buyer to buy services such as flight tickets on-line and receive the order information back in the purchasing system of the buyer.

G-42-005

The profile enables buyers to configure their own products (i.e. pc’s or furniture) on the seller’s website, and receive order information back to the purchasing system of the buyer.,

G-42-006

Increased order accuracy by ensuring high data quality in the purchasing system of the buyer.

G-42-007

Personalized shopping experience - the seller’s product/services can be presented with photos, customized promotions and recommended accessories

G-42-008

The profile enables the buyer to receive the order information back in the purchasing system of the buyer also in the cases where the order is sent via e-mail, made in a telephone call or on a visit to the seller’s store.

G-42-009

The profile enables the buyer to instruct the seller to send a reference chosen by the buyer in the Order Agreement transaction.

G-42-010

The buyer wants precise order to invoice matching.

G-42-011

The seller wants an efficient way to report services rendered when buyer cannot order through the purchasing system.

G-42-012

The seller wants to match order and invoice automatically

G-42-013

The buyer wants to document the services rendered based on contract when the order was executed by other channels or based on a service agreement

G-42-014

The buyer wants to receive order agreement in a structured way in a general and interoperable file-format with no need for custom mappings or conversions.

G-42-015

The seller wants order agreement using generally accepted standard formats/specifications.

G-42-016

A buyer wants to collect certificate and label information in his orders for analytical purposes.

2.4. Parties and roles

The table below gives the definitions of the parties and roles of the ordering process.

Business partners

Description

Customer

The customer is the legal person or organization who is in demand of a product or service.

Examples of customer roles: buyer, consignee/delivery part, debtor, contracting body.

Supplier

The supplier is the legal person or organization who provides a product or service.

Examples of supplier roles: seller, consignor, creditor, economic operator.

Role/actor

Description

Buyer (BuyerCustomerParty)

The buyer is the legal person or organization acting on behalf of the customer and who buys or purchases the goods or services.

Seller (SellerSupplierParty)

The seller is the legal person or organization acting on behalf of the supplier and who sells goods or services to the customer.

The following diagram links the business processes to the roles performed by the Business Partners.

42Aparties

2.5. Benefits

  • The ability to use existing order-invoice-matching processes even if order is not issued from a procurement system.

  • Capture ordering actions that happen in other processes such as web shops, phone or by requisition at warehouse/store and so forth.

  • Visibility of whole spending analysis in the ordering module by importing orders that are not sent directly from the ordering module.

  • Support for ordering processes where products/services are not necessarily described as standardized catalogue items.

2.6. Interoperability

This Peppol BIS structure is based on the European Interoperability Framework 2.0. Peppol BIS applies the Framework as follows:

  1. Legal Interoperability

    • Legal:

      • In implementations supporting public sector buyers, the use of the Punch out BIS has to be monitored in order to secure that the buyers act in line with EU procurement directives.

  2. Organizational interoperability

    • Organization (Organization/Business):

      • This Peppol BIS supports B2B and B2G.

      • This Peppol BIS supports cross border, regional and domestic ordering in EU and EEA.

      • This Peppol BIS can function as a component in an EDI agreement within a trading community.

      • This Peppol BIS supports linking of business processes within the sending and receiving organization. The process of order transmission in electronic form can be linked into internal processes of both sender and receiver, which may differ for various reasons.

    • Organization (Process):

      • This Peppol BIS supports a set of “common business processes” that is assumed to be supported by most enterprises whether public or private. These are processes that are used widely or understood as being relevant for most companies.

  3. Semantic interoperability

    • Semantic: The set of information elements is assumed to be sufficient to support organizational business and processing requirements stated above.

      • A CORE Order Agreement cart message:

        • Data model, a set of elements that the receiver MUST be able to process.

        • Business rules, a set of business rules that ensure a common way of processing the information elements. The rules are stated in a way that allows for automated validation of document instances. Issuers and receivers can verify that the exchanged document conformes to the rules of this BIS.
          Peppol adds business rules on top of the data model to clarify certain design choices left open by the {cenbii}. These choices are intended to lower the implementation threshold by limiting options for implementers and thereby increase interoperability of Peppol punch out transactions.

  4. Technical interoperability

    • Technical Interaction (Process and semantic implementation):

      • Binding to OASIS UBL 2.1, see UBL 2.1

      • ISO/IEC 19757-3 Schematron, for automation of document validation, see Schematron

      • XSLT Stylesheet for presentation of content, see [XSLT]

    • Technical Interaction (eSignature Validation):

      • Not mandatory in this Peppol BIS. Not supported.

3. Process and typical use cases

The order agreement BIS includes the sending of information on agreed products/services from a Seller to a Buyer.

3.1. Process flow

The order agreement process flow can be described as follows:

Possible start positions:
  1. A Buyer makes a purchase of goods or services from the Seller.

  2. A Seller reports one or more accumulated purchases made under a framework agreement to the Buyer.

End positions:
  1. A purchase has been recorded in the Buyer´s purchasing system. The seller proceeds to invoice accordingly.

An Order Agreement may refer to a framework agreement for its terms and conditions; otherwise the Buyer’s terms and conditions apply.

3.2. Business process Diagram

3.2.1. Legend for BPMN diagrams

The diagrams are expressed in the BPMN notation. The diagram below serves as an explanation for the diagrams used in the process descriptions.

bpmn legend
Figure 1. BPMN legend

The following diagram shows the choreography of the business process implemented by the BIS.

oa bpmn 1

Categories

Description and Values

Description

The buyer doesn’t use the purchasing system to create an order. It’s done outside of this system.

The seller creates an order in his ordering system based on requirements from the buyer and, after agreeing/committing to it, sends a copy of the order as an Order agreement to the buyer.

Pre-conditions

The seller’s ordering system must be able to send Order agreement transactions.

The buyer’s purchasing system must be able to receive Order agreement transactions.

The content of the order is agreed through use of web shop, phone, email, physical visit to shop or other means.

Post-conditions

The buyer has received an order agreement that is recorded in the purchasing system.

Legal Implications

By providing an Order agreement transaction the Seller commits himself the, quantities, prices and terms stated in the Order agreement transaction.

3.3. Use case 1 – Web store used for booking tickets

This use case describes the process where a customer/buyer orders tickets.

Use Case number

1

Use Case Name

Web store used for booking tickets

Use Case Description

The buyer uses a website to buy tickets, such as for airfare or events.

Parties involved

  • Buyer

  • Seller

Assumptions

The seller has a website that allows the buyer to select and order tickets.
The buyer has an account with the seller with necessary details to send him an order agreement.

The flow

The buyer uses the website to book tickets. The buyer receives the tickets in the way as selected in the web shop (e.g. mobile ticket or pdf). The buyer then ends the web shop session. The purchase is recorded in the seller’s system.

An order agreement transaction with all necessary information is sent from the seller’s system to the buyer’s purchasing system. The order agreement is recorded in the buyer’s purchasing system.

An invoice is sent to the buyer, but this is outside of this BIS.

If the buyer wishes to change a ticket in accordance with the its rules then he reenters the web store, changes the ticket and receives a new order agreement. The change procedure is a repetition of the initial one.

Result

The buyer and the seller have reached an agreement. An order has been placed for tickets and the buyer has received a structured message with its details. If the invoice has an order reference, the invoice can be matched automatically.

XML example file

See Appendix A for a sample file illustrating Use Case 1.

3.4. Use case 2 – Web shop used for ordering items

This use case describes the process where a customer/buyer orders products in a web shop.

Use Case number

2

Use Case Name

Web shop used for ordering items

Use Case Description

The buyer uses a website to buy items.

Parties involved

  • Buyer

  • Seller

Assumptions

The seller has a website that allows the buyer to select and order items.
The buyer has an account with the seller with necessary details to send him an order agreement.

The flow

The buyer is working in the in-house purchasing system, selects a seller that has a web shop, and clicks to see that seller’s products.

The buyer searches the website for items needed, and choose to add some to the order agreement. It is clearly visible which items are contracted. After selecting all required items, the buyer then chooses to buy the selected items. When the ordering is finalized in the web shop, the buyer ends the web shop session. The purchse is recorded in the seller’s system.

An order agreement transaction with item information of the purchased items is sent from the seller to the. The order agreement is recorded in the buyer’s purchasing system.

After the delivery of the goods the seller sends an invoice which matches the order and the delivery, but this is outside of this BIS.

Result

The buyer and the seller have reached an agreement. An order has been placed and the buyer has received a structured message with the order details. If the invoice has an order reference, the invoice can be matched automatically.

XML example file

See Appendix A for a sample file illustrating Use Case 2.

3.5. Use case 3 – Telephone and e-mail is used to order items

Use Case number

3

Use Case Name

Telephone or e-mail order

Use Case Description

Buyer makes a purchase by calling the seller by telephone or by sending an email.

Parties involved

  • Buyer

  • Seller

Assumptions

The buyer has an account with the seller with necessary details to send him an order agreement.

The flow

The buyer is working in his purchasing system, and need to by printers and selects a seller of printers. The seller’s items are not in the purchasing system and the seller doesn’t offer a web shop. The buyer calls the seller on the telephone.

The buyer orders the printer directly during the phone call, and also informs the seller what reference to use.

An order agreement transaction with item information and price of the selected items is sent from the seller to the buyer’s purchasing system. The order agreement is recorded in the buyer’s purchasing system

After the delivery of the goods, the seller sends an invoice which matches the order and the delivery, but this is outside of this BIS.

Result

The buyer and the seller have reached an agreement. An order has been placed and the buyer has received a structured message with the order details. If the invoice has an order reference, the invoice can be matched automatically.

XML example file

See Appendix A for a sample file illustrating Use Case 3.

3.6. Use case 4 – Buyer visits the seller’s physical store.

This use case describes a process where the buyer physically enters the sellers store to buy and possibly take delivery of goods.

Use Case number

4

Use Case Name

User configures product/services

Use Case Description

A buyer physically makes a purchase and takes delivery.

Parties involved

  • Buyer

  • Seller

Assumptions

The buyer has an account with the seller with necessary details to send him an order agreement.

The flow

The buyer urgently need some items and may wish to discuss this with the seller before buying the items.

After selecting the items he needs the buyer gets a receipt for the selected items. He may bring with him all the items when leaving the store or schedule a later delivery.

The seller registers the order in the ordering system including a reference such as requisition number, person id, project id etc.

An order agreement transaction with item information and price of the selected items is sent from the seller to the buyer’s purchasing system. The order agreement is recorded in the buyer’s purchasing system

The buyer then follows the normal procedure to, if needed, complete the order.

The seller sends an invoice which matches the order and delivery, but this is outside of this BIS.

Result

The buyer and the seller has reached an agreement. An order has been placed and the buyer has taken delivery of the products. The buyer has received a structured message with the order details. The invoice has a reference, to match the order.

XML example file

See Appendix A for a sample file illustrating Use Case 4.

3.7. Use case 5 – Framework contract

The buyer has made a framework agreement with the seller for services such as maintenance or consulting. The framework agreement sets limits and terms within which the seller may provide services without individual orders from the buyer.

Use Case number

5

Use Case Name

Maintenance based on framework contract

Use Case Description

A seller who has a framework agreement that contracts him for certain services, items or consulting may react to events as contracted and at the end of a period send an order agreement listing the services that were carried out.

Examples include:

  • A maintenance services that monitors a building and, for example, fixes windows, doors and other things that need maintenance as identified.

  • A computer service provider monitors systems and reacts immediately to incidents such as system down time or errors.

  • An accounting services contracted by the buyer handles various filings and reports as required.

  • A seller of supplies has been contracted to monitor the stock levels for certain items and restock as needed to maintain the agreed levels.

In each of these examples the buyer has made a framework contract with the seller allowing the seller to react to defined but not previously known events without receiving an order or request from the buyer for each event.

Parties involved

  • Buyer

  • Seller

Assumptions

The seller and buyer has a framework contract that define the service to be provided and its limits.

The flow

The seller of the services or items reacts to events as defined in the contract and carries out the service or delivers the items as contracted.

Periodically, for example monthly, the seller lists all services and items that have been provided during the period. This is listed with order agreement lines and the total of the order agreement represents the total value of the services and items provided during the period which will be invoice by the seller. The seller sends the order agreement to the buyer who records it in his system.

The seller proceeds to invoice immediately unless otherwise directed by the framework agreement.

The buyer may have internal processes that verify these kind of order agreements differently than those initiated by himself.

Result

The buyer has registered a purchase order in his systems that allow him to order to invoice matching when the invoice is received.

XML example file

See Appendix A for a sample file illustrating Use Case 5.

4. Semantic datatypes

Semantic data types are used to bridge the gap between the semantic concepts expressed by the information elements and the technical implementation. The semantic data types define the allowed value domain for the content, and any additional information components (attributes) needed in order to ensure its precise interpretation.

4.1. Primitive types

Semantic data type content may be of the following primitive types. These primitive types were taken from ISO 15000-5:2014, Annex A.

Primitive type Definition

Binary

A set of finite-length sequences of binary digits.

Date

Time point representing a calendar day on a time scale consisting of an origin and a succession of calendar ISO 8601:2004.

Decimal

A subset of the real numbers, which can be represented by decimal numerals.

String

A finite sequence of characters.

4.2. Semantic data types

The different semantic data types are described in the tables below, where various features such as attributes, format, and decimals as well as the basic type are defined for each semantic data type. They are based on ISO 15000-5:2014.

When used in an instance document, each data element will contain data. In the below tables this is identified as the “content”. Whenever a business term is used this term shall always have content and therefore the content is always mandatory.

4.2.1. Amount

An amount states a numerical monetary value. The currency of the amount is defined as a separate business term.

Amount is floating up to two fraction digits.
Component Use Primitive Type Example

Content

Mandatory

Decimal

10000.25

4.2.2. Price Amount

A price amount states a numerical monetary amount value for data elements that contain item prices that may be multiplied by item quantities. The currency of the amount is defined as a separate business term.

Unit price amount does not set restrictions on number of decimals, as contrast to the Amount type
Component Use Primitive Type Example

Content

Mandatory

Decimal

10000.1234

4.2.3. Percentage

Percentages are given as fractions of a hundred (per cent) e.g. the value 34,78 % in percentage terms is given as 34,78.

No restriction on number of decimals for percentages.
Component Use Primitive Type Example

Content

Mandatory

Decimal

34.7812

4.2.4. Quantity

Quantities are used to state a number of units such as for items. The code for the Unit of Measure is defined as a separate business term.

No restriction on number of decimals for quantities.
Component Use Primitive Type Example

Content

Mandatory

Decimal

10000.1234

4.2.5. Code

Codes are used to specify allowed values in elements as well as for lists of options. Code is different from Identifier in that allowed values have standardized meanings that can be known by the recipient.

Codes shall be entered exactly as shown in the selected code list
Component Use Primitive Type Example

Content

Mandatory

String

Abc123

4.2.6. Identifier

Identifiers (IDs) are keys that are issued by the sender or recipient of a document or by a third party.

The use of the attributes is specified for each information element.
Component Use Primitive Type Example

Content

Mandatory

String

abc:123-DEF

Scheme identifier

Conditional

String

0088

Scheme version identifier

Conditional

String

1.0

4.2.7. Date

Dates shall be in accordance to the “Calendar date complete representation” as specified by ISO 8601:2004, format YYYY-MM-DD.

Dates shall not include timezone information.
Table 2. EN 16931_ Date. Type
Component Use Primitive Type Example

Content

Mandatory

Date

2017-12-01

4.2.8. Time

Time shall be in accordance to the “Extended time format” as specified by ISO 8601:2004, format [hh]:[mm]:[ss].

Time shall not include timezone information. Decimal fraction on seconds SHALL not be used.
Table 3. EN 16931_ Date. Type
Component Use Primitive Type Example

Content

Mandatory

Date

09:30:12

4.2.9. Document Reference

Document Reference Types are identifiers that were assigned to a document or document line.

Table 4. Document Reference. Type
Component Use Primitive Type Example

Content

Mandatory

String

abc:123-DEF

4.2.10. Text

Text is the actual wording of anything written or printed. Line breaks in the text may be present, and any line breaks should be preserved and respected by the receiver’s system

Component Use Primitive Type Example

Content

Mandatory

String

5% allowance when paid within 30 days

4.2.11. Binary objects

Binary objects can be used to describe files which are transmitted together with the business document. Attachments shall be transmitted together with the business document. The binary object has two supplementary components: a Mime Code, which specifies the Mime type of the attachment and a Filename that is provided by (or on behalf of) the sender of the business document.

Component Use Primitive Type Example

Content

Mandatory

Binary

QmFzZTY0IGNvbnRlbnQgZXhhbXBsZQ==

Mime Code

Mandatory

String

image/jpeg

Filename

Mandatory

String

drawing5.jpg

4.2.12. Boolean

Boolean indicators are used to specify the two allowed values, true or false. All elements of datatype Boolean, must have either true or false as their value.

Component Use Primitive Type Example

Content

Mandatory

Boolean

true

5. Code lists

5.1. Code lists for coded elements

Any element with the semantic data type = code, can mandate the use of a specific code list (or a fixed value). The applicable code lists can be found in the Code list section. In this section, you can find the valid codes, their names and description, and also links to where the same code list is used elsewhere in the transaction, or in other Peppol BIS v3. documents.

5.2. Code list for identifiers

All party identifiers (cac:PartyIdentification/cbc:ID) and party legal registration identifier (cac:PartyLegalEntity/cbc:CompanyID) has an optional scheme identifier attribute (@schemeID). If used, the value shall be chosen from the code list ICD codes

Examples of usage in cac:PartyIdentification
<cac:PartyIdentification>
        <cbc:ID schemeID="0088">5790000435968</cbc:ID> (1)
</cac:PartyIdentification>
1 schemeID attribute is optional, but when used, the codes must be from ICD codes

5.2.2. Electronic address identifier scheme identifier

All electronic address identifiers (cbc:EndpointID/@schemeID) use the Electronic Address Scheme code list (EAS), maintained by CEF (CEF Code lists).

Valid values are found here: EAS codes.

Examples of usage in cbc:EndpointID
<cbc:EndpointID schemeID="0184">DK87654321</cbc:EndpointID> (1)
1 schemeID attribute is mandatory

6. Calculations

6.1. Calculation of TAX amounts

6.1.1. Total TAX amount

The total TAX amount can be provided without providing the TAX breakdown, but if the TAX breakdown is present, the total TAX amount is the sum of all TAX Category TAX amounts.

\$"Total TAX amount" = sum("TAX category tax amount")\$

6.1.2. TAX Breakdown

One TAX Breakdown shall be provided for each distinct combination of TAX category code and TAX rate found in either the line TAX information or the Document level allowance or charges.

For each distinct combination of TAX category code and TAX rate the calculations are:

\$"TAX category taxable amount" = sum("Line net amounts")\$
\$+ "Document level charge amount" - "Document level allowance amount"\$

\$"TAX category tax amount" = "TAX category taxable amount" times ("TAX rate" div 100)\$

For TAX Breakdown where the TAX Category indicates the invoice is not subject to TAX (e.g. (O) in EU), then the TAX category tax amount shall be zero.

Please note that for the TAX rate, only significant decimals should be considered, i.e any difference in trailing zeros should not result in different TAX breakdowns.

Example 1. Example where TAX is VAT.

Line 1 has category code = S and VAT rate = 25
Line 2 has category code = S and VAT rate = 25.00
This should result in only one VAT Breakdown.

UBL Example of tax total and tax breakdown, when TAX is VAT.
<cac:TaxTotal>
        <cbc:TaxAmount currencyID="EUR">283.2</cbc:TaxAmount>
        <cac:TaxSubtotal>
                <cbc:TaxableAmount currencyID="EUR">1200</cbc:TaxableAmount>(1)
                <cbc:TaxAmount currencyID="EUR">283.20</cbc:TaxAmount>(2)
                <cac:TaxCategory>
                        <cbc:ID>S</cbc:ID>
                        <cbc:Percent>23.6</cbc:Percent> (3)
                        <cac:TaxScheme>
                                <cbc:ID>VAT</cbc:ID>
                        </cac:TaxScheme>
                </cac:TaxCategory>
        </cac:TaxSubtotal>
</cac:TaxTotal>
1 The class cac:TaxCategory is used for tax category information
2 TAX category according to codelist Code list UNCL5305
3 TAX rate

6.2. Calculation of totals

The following elements show the legal monetary totals

Element Description Formula

cbc:LineExtensionAmount

Sum of line net amounts

\$sum("cac:OrderLine/LineItem/cbc:LineExtensionAmount")\$

cbc:AllowanceTotalAmount

Sum of allowances on document level

\$sum("cac:AllowanceCharge[ChargeIndicator='false']/cbc:Amount")\$

cbc:ChargeTotalAmount

Sum of charges on document level

\$sum("cac:AllowanceCharge[ChargeIndicator='true']/cbc:Amount")\$

cbc:TaxExclusiveAmount

Invoice total amount without VAT

\$\ \ \ \ "cac:LegalMonetaryTotal/cbc:LineExtensionAmount"\$
\$– \ "cac:LegalMonetaryTotal/cbc:AllowanceTotalAmount"\$
\$+ \ "cac:LegalMonetaryTotal/cbc:ChargeTotalAmount"\$

cbc:TaxInclusiveAmount

Invoice total amount with VAT

\$\ \ \ \ "cac:LegalMonetaryTotal/cbc:TaxExclusiveAmount"\$
\$+ \ "cac:TaxTotal/cbc:TaxAmount"\$

cbc:PrepaidAmount

Amount allready paid

Not applicable

cbc:PayableRoundingAmount

Amount added for rounding of the payable amount

Not applicable

cbc:PayableAmount

Amount due for payment

\$\ \ \ \ "cac:LegalMonetaryTotal/cbc:TaxInclusiveAmount"\$
\$- \ "cac:LegalMonetaryTotal/cbc:PrepaidAmount"\$
\$+ \ "cac:LegalMonetaryTotal/cbc:PayableRoundingAmount"\$

7. Description of selected parts of the order agreement message

Following clauses describe the use of individual sections of the order agreement transaction.

7.1. Parties

The following parties/roles may be specified in the message:

7.1.1. SellerSupplierParty (Seller)

The seller is the legal person or organization acting on behalf of the supplier and who sells goods or services to the buyer. The seller is mandatory in the Peppol BIS Order Agreement message.

Example
<cac:SellerSupplierParty>
        <cac:Party>
                <cbc:EndpointID schemeID="0088">5790000436095</cbc:EndpointID>
                <cac:PartyIdentification>
                        <cbc:ID schemeID="0007">5541277711</cbc:ID>
                </cac:PartyIdentification>
                <cac:PostalAddress>
                        <cbc:StreetName>Apt 56B, Whitehaven Mansions</cbc:StreetName>
                        <cbc:AdditionalStreetName>Sandhurst Sq</cbc:AdditionalStreetName>
                        <cbc:CityName>Brussels</cbc:CityName>
                        <cbc:PostalZone>1001</cbc:PostalZone>
                        <cbc:CountrySubentity>Brussels-Capital</cbc:CountrySubentity>
                        <cac:Country>
                                <cbc:IdentificationCode>BE</cbc:IdentificationCode>
                        </cac:Country>
                </cac:PostalAddress>
                <cac:PartyLegalEntity>
                        <cbc:RegistrationName>Seller Company Ltd</cbc:RegistrationName>
                </cac:PartyLegalEntity>
                <cac:Contact>
                        <cbc:Name>Hercule Poirot</cbc:Name>
                        <cbc:Telephone>123456</cbc:Telephone>
                        <cbc:ElectronicMail>mail@work.be</cbc:ElectronicMail>
                </cac:Contact>
        </cac:Party>
</cac:SellerSupplierParty>

7.1.2. BuyerCustomerParty (Buyer)

The buyer is the legal person or organization acting on behalf of the customer and who buys or purchases the goods or services. The buyer is mandatory in the Peppol BIS Order Agreement message.

Example
<cac:BuyerCustomerParty>
        <cac:Party>
                <cbc:EndpointID schemeID="0088">5790000436095</cbc:EndpointID>
                <cac:PartyIdentification>
                        <cbc:ID schemeID="0007">5541277711</cbc:ID>
                </cac:PartyIdentification>
                <cac:PostalAddress>
                        <cbc:StreetName>Apt 56B, Whitehaven Mansions</cbc:StreetName>
                        <cbc:AdditionalStreetName>Sandhurst Sq</cbc:AdditionalStreetName>
                        <cbc:CityName>Brussels</cbc:CityName>
                        <cbc:PostalZone>1001</cbc:PostalZone>
                        <cbc:CountrySubentity>BE</cbc:CountrySubentity>
                        <cac:Country>
                                <cbc:IdentificationCode>SE</cbc:IdentificationCode>
                        </cac:Country>
                </cac:PostalAddress>
                <cac:PartyLegalEntity>
                        <cbc:RegistrationName>Buyer Ltd</cbc:RegistrationName>
                </cac:PartyLegalEntity>
        </cac:Party>
</cac:BuyerCustomerParty>

7.1.3. OriginatorCustomerParty (Originator)

The unit initiating or requesting the ordered items. Most often the end user. The originator information is optional in the Peppol BIS Order Agreement message.

Example
<cac:OriginatorCustomerParty>
        <cac:Party>
                <cac:PartyIdentification>
                        <cbc:ID schemeID="0007">5541277711</cbc:ID>
                </cac:PartyIdentification>
                <cac:PartyName>
                        <cbc:Name>Information services</cbc:Name>
                </cac:PartyName>
        </cac:Party>
</cac:OriginatorCustomerParty>

7.1.4. AccountingCustomerParty (Invoicee)

The invoicee is the legal person or organization acting on behalf of the customer and who receives the invoice for the order. The invoicee information is optional in the Peppol BIS Order Agreement message.

Example
<cac:AccountingCustomerParty>
        <cac:Party>
                <cac:PartyIdentification>
                        <cbc:ID schemeID="0007">5541277711</cbc:ID>
                </cac:PartyIdentification>
                <cac:PartyName>
                        <cbc:Name>Information services</cbc:Name>
                </cac:PartyName>
        </cac:Party>
</cac:AccountingCustomerParty>

7.2. Delivery

Delivery gives information on when and where the goods and services are delivered.

  • Delivery location (cac:Delivery/cac:DeliveryTerms/cac:DeliveryLocation) is where the supplier leaves the packages.

  • Delivery party (cac:Delivery/cac:DeliveryParty) is the party who will get the ordered items.

Delivery special terms may be used to inform how the the goods or service is delivered. E.g.

  • A ticket may be delivered as a pdf in mail - “Mail”.

  • Goods may have been collected at the store – “Customer pick up“

The delivery information is optional in the Peppol BIS Order Agreement message.

Example
<cac:Delivery>
        <cac:PromisedDeliveryPeriod>
                <cbc:StartDate>2016-08-20</cbc:StartDate>
                <cbc:StartTime>12:00:00</cbc:StartTime>
                <cbc:EndDate>2016-08-30</cbc:EndDate>
                <cbc:EndTime>18:00:00</cbc:EndTime>
        </cac:PromisedDeliveryPeriod>
        <cac:DeliveryParty>
                <cac:PartyIdentification>
                        <cbc:ID schemeID="0007">5541277711</cbc:ID>
                </cac:PartyIdentification>
                <cac:PartyName>
                        <cbc:Name>Delivery party name</cbc:Name>
                </cac:PartyName>
        </cac:DeliveryParty>

</cac:Delivery>

<cac:DeliveryTerms>
        <cbc:ID>1</cbc:ID>
        <cbc:SpecialTerms>Customer pick up</cbc:SpecialTerms>
</cac:DeliveryTerms>

7.3. References

When sending the order agreement transaction the seller may include a reference that the buyers gave to him during the purchase. This reference can be of different nature and since it originates from the buyer it is understood by him.

Example
<cbc:CustomerReference>Buyer reference id</cbc:CustomerReference>

The order agreement may refrence a previous order agreement. This may be relevant, as example, when the buyer has changed a previous order.

Example
<cac:OrderReference>
        <cbc:ID>Order id</cbc:ID>
</cac:OrderReference>

The order agreement may reference a contract that applies to the purchase.

Example
<cac:Contract>
        <cbc:ID>contract id</cbc:ID>
</cac:Contract>

7.4. Attachments on header level

Non-XML documents can be sent as attachments to the Peppol BIS Order Agreement. This could be time sheets or other documents relevant for the order agreement. The attachment can either be sent as a binary object encoded in Base64 embedded in the message or as a URI to an external address as a link.

It is recommended to send attachments as embedded, binary objects and not as external references.

Attachments should be used for additional information and not as order copies.
Example of attachment as an embedded, binary object in an Peppol BIS Order Agreement message
<cac:AdditionalDocumentReference>
        <cbc:ID>Document id</cbc:ID>
        <cbc:DocumentType>Document description</cbc:DocumentType>
        <cac:Attachment>
                <cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf" filename="file.pdf">
                        UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</cbc:EmbeddedDocumentBinaryObject>
        </cac:Attachment>
</cac:AdditionalDocumentReference>

7.5. Attachments and document references on line level

Non-XML documents can be sent as attachments to the Peppol BIS Order Agreement on line level. This could comprise item specifications, time sheets or other documents relevant for the particular line in the order agreement. See the above information regarding attachments.

Example of attachment as an embedded, binary object in an Peppol BIS Order Agreement message on line level.
<cac:ItemSpecificationDocumentReference>
        <cbc:ID>doc id</cbc:ID>
        <cbc:DocumentType>Item specs</cbc:DocumentType>
        <cac:Attachment>
                <cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf"
                        filename="specs.pdf">
                        UjBsR09EbGhjZ0dTQUxNQUFBUUNBRU1tQ1p0dU1GUXhEUzhi</cbc:EmbeddedDocumentBinaryObject>
        </cac:Attachment>
</cac:ItemSpecificationDocumentReference>
Example of a Link to a downloadable ticket
<cac:ItemSpecificationDocumentReference>
        <cbc:ID>doc id</cbc:ID>
        <cbc:DocumentType>Item specs</cbc:DocumentType>
        <cac:Attachment>
                <cac:ExternalReference>
                        <cbc:URI>https://joinup.ec.europa.eu/svn/peppol/PostAward/Ordering28A/20160310%20-%20PEPPOL_BIS_28a-101.pdf</cbc:URI>
                </cac:ExternalReference>
        </cac:Attachment>
</cac:ItemSpecificationDocumentReference>

7.6. Product identification

Product identification may be done using the identifiers described below:

  • Sellers ID

  • Standard ID, e.g. the GS1 Global Trade Item Number (GTIN)

  • Buyers ID

The order agreement requires that an item has an identifier. This can be either the sellers identifier or a standard identifier. Which identifier to use depends on what is known at the time of the purchase or what is commonly used in the relevant business sector.

Example of an Peppol BIS Order Agreement item using both Sellers ID and Standard ID (GTIN)
<cac:SellersItemIdentification>
        <cbc:ID>123</cbc:ID>
</cac:SellersItemIdentification>
<cac:StandardItemIdentification>
        <cbc:ID schemeID="0160">73123456001233</cbc:ID>
</cac:StandardItemIdentification>

7.7. Product name and description

The Product name must be sent in the element cac:Item/cbc:Name on line level. Description of a product can be sent in cac:Item/cbc:Description. The Product name is often sent in the order agreement from the buyer to the seller.

Example in an Peppol BIS Order Agreement message
<cac:Item>
        <cbc:Description>Description of the item</cbc:Description>
        <cbc:Name>Item name</cbc:Name>

7.8. Item labelling

Information about the items environmental, social, ethical and quality type of labelling. The UBL structure used for item labeling requires certain elements in addition to those used by this BIS. To fulfill the UBL requirements these are included with the dummy value NA.

Example
<cac:Certificate>
        <cbc:ID>EU Ecolabel</cbc:ID>
        <cbc:CertificateTypeCode>NA</cbc:CertificateTypeCode>
        <cbc:CertificateType>Environmental</cbc:CertificateType>
        <cbc:Remarks>Item label value</cbc:Remarks>
        <cac:IssuerParty>
                <cac:PartyName>
                        <cbc:Name>NA</cbc:Name>
                </cac:PartyName>
        </cac:IssuerParty>
        <cac:DocumentReference>
                <cbc:ID>Item label reference</cbc:ID>
        </cac:DocumentReference>
</cac:Certificate>

7.9. Contracted item

If the purchased item is offered in accordance to an existing contract, this should be indicated in the order agreement message.

Example
<cac:TransactionConditions>
        <cbc:ActionCode>CT</cbc:ActionCode>
</cac:TransactionConditions>

7.10. Classification

An item may be classified according to UNSPSC being the mandatory public classification schemes in some countries/sectors. As there is currently no code for UNSPSC in the used code list UNCL 7143, the code "MP" (Product/service identification number) is used. Products can also be classified according to regulatory schemes or classification schemes used in certain business sectors.

Example:
<cac:CommodityClassification>
        <cbc:ItemClassificationCode listID="MP" listVersionID="20.0601">14111511</cbc:ItemClassificationCode>
</cac:CommodityClassification>

7.11. Quantities and units

Various Quantities and Units can be stated in the Peppol BIS Order Agreement. These are both related to the ordering process and the logistics process.

The table below lists quantities and units in the format. To all quantities there must be a valid Unit of measure according to the Code list.

Element name / (Tag name) Description

Price Quantity / (BaseQuantity)

Quantity related to Price.

Order Quantity / (Quantity)

Quantity that is ordered, e.g. number of pieces or volume in litre .

Example of an order agreement line with a quantity of 120 pieces (cbc:Quantity) and price is given per 12 items. When calculating the line amount the price is applied pr 12 pieces, that is 120/12x50 = €500
                <cac:LineItem>
                        <cbc:ID>1</cbc:ID>
                        <cbc:Note>Line note</cbc:Note>
                        <cbc:Quantity unitCode="C62">120</cbc:Quantity>
                        <cbc:LineExtensionAmount currencyID="EUR">500</cbc:LineExtensionAmount>

<!-- code omitted for clarity -->
                        <cac:Price>
                                <cbc:PriceAmount currencyID="EUR">50</cbc:PriceAmount>
                                <cbc:BaseQuantity unitCode="C62">12</cbc:BaseQuantity>
                        </cac:Price>

7.12. Prices

Prices must be exchanged in the Order Agreement transaction. The price may be 0 (zero)

Price sent is related to the articles or services within this order agreement

Prices includes allowances and/or charges but exclude TAX amounts

Example of price information in an Order Agreement message
<cac:Price>
        <cbc:PriceAmount currencyID="EUR">50</cbc:PriceAmount>
        <cbc:BaseQuantity unitCode="C62">1</cbc:BaseQuantity>
</cac:Price>

7.13. Allowances and Charges

The order agreement transaction has Allowance/charge on header level.

The element cac:AllowanceCharge with sub element cbc:ChargeIndicator indicates whether the instance is a charge (true) or an allowance (false).

Information on allowance and/or charges applies to the whole order agreement and is included in the calculation of the order agreement total amount.

  • Several allowances and charges may be supplied

  • Specification of TAX for allowances and charges, cac:TaxCategory with sub elements, shall be supplied

  • The sum of all allowances and charges on the header level shall be specified in cbc:AllowanceTotalAmount and cbc:ChargeTotalAmount respectively. See Calculation of totals

Calculation of allowance/charge amount

Allowance and charge on document level consists of elements carrying information on the allowance/charge base amount and the allowance/charge percentage. These are, if present in the invoice instance, used for calculating the allowance/charge amount.

If base amount is present, the percentage shall also be present, and if percentage is present, the base amount shall also be present, and the calculation of the amount shall be:

\$"Amount" = "Base amount" times ("Percentage" div 100)\$

UBL example of Allowances and Charges on the document level, when TAX is VAT.
<cac:AllowanceCharge>
        <cbc:ChargeIndicator>true</cbc:ChargeIndicator>(1)
        <cbc:AllowanceChargeReasonCode>FC</cbc:AllowanceChargeReasonCode>
        <cbc:AllowanceChargeReason>Freight service</cbc:AllowanceChargeReason>
        <cbc:MultiplierFactorNumeric>2</cbc:MultiplierFactorNumeric>(4)
        <cbc:Amount currencyID="EUR">20</cbc:Amount> (5)
        <cbc:BaseAmount currencyID="EUR">1000</cbc:BaseAmount>(3)
        <cac:TaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>23.6</cbc:Percent>
                <cac:TaxScheme>
                        <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
        </cac:TaxCategory>
</cac:AllowanceCharge>
<cac:AllowanceCharge>
        <cbc:ChargeIndicator>false</cbc:ChargeIndicator>(2)
        <cbc:AllowanceChargeReasonCode>65</cbc:AllowanceChargeReasonCode>
        <cbc:AllowanceChargeReason>Production error discount</cbc:AllowanceChargeReason>
        <cbc:Amount currencyID="EUR">10</cbc:Amount>
        <cac:TaxCategory>
                <cbc:ID>S</cbc:ID>
                <cbc:Percent>23.6</cbc:Percent>
                <cac:TaxScheme>
                        <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
        </cac:TaxCategory>
</cac:AllowanceCharge>
1 ChargeIndicator = true to indicate a charge
2 ChargeIndicator = false to indicate an allowance
3 Base amount, to be used with the percentage to calculate the amount
4 Charge percentage
5 \$"Amount" = "Base amount" times ("Percentage" div 100)\$

7.14. TAX information (TAX)

The chapters below describe the different TAX informations that can be provided in this BIS. In this context the term TAX applies to taxes such as VAT, GST and Sales Tax.

Please also see Code list UNCL5305 for details on the TAX category code list, and Total TAX amount for detailed explanation and example on how to perform the calculations for TAX Breakdown.

7.14.1. Line TAX Category

TAX information on line level is provided in the class cac:ClassifiedTaxCategory.

Each line may have the item TAX information including category code and percentage.

UBL example of line TAX category, when TAX is VAT
<cac:ClassifiedTaxCategory>
    <cbc:ID>S</cbc:ID> (1)
    <cbc:Percent>18</cbc:Percent>(2)
    <cac:TaxScheme>
        <cbc:ID>VAT</cbc:ID>(3)
    </cac:TaxScheme>
</cac:ClassifiedTaxCategory>
1 TAX category according to codelist Code list UNCL5305
2 The TAX percentage rate that applies to the item unless specific trade reasons apply such as exemptions.
3 Value must identify the correct tax type. For example VAT, GST or sales tax.

7.14.2. TAX info for allowance or charge

Document level allowance/charge is stated using the UBL element cac:AllowanceCharge. Further details on allowance and charge can be found in Allowances and Charges.

Each document level charge or allowance must have the Document level allowance or charge TAX category code, and for all TAX categories except when tax category indicates that the invoice is not subject to TAX (e.g. (O) in EU), then the TAX rate shall be provided.

UBL Example of a charge with tax category information, when the TAX is VAT.
<cac:AllowanceCharge>
        <cbc:ChargeIndicator>true</cbc:ChargeIndicator>
        <cbc:AllowanceChargeReason>Packing cost</cbc:AllowanceChargeReason>
        <cbc:Amount currencyID="EUR">200</cbc:Amount>
        <cac:TaxCategory>(1)
                <cbc:ID>S</cbc:ID>(2)
                <cbc:Percent>23.6</cbc:Percent>(3)
                <cac:TaxScheme>
                        <cbc:ID>VAT</cbc:ID>
                </cac:TaxScheme>
        </cac:TaxCategory>
</cac:AllowanceCharge>
1 The class cac:TaxCategory is used for tax category information
2 TAX category according to codelist Code list UNCL5305
3 TAX rate

8. Peppol Identifiers

Peppol has defined a Peppol Policy for identifiers, policy 8 that specifies how to use identifiers in both its transport infrastructure and within the documents exchanged across that infrastructure. It also introduces principles for any identifiers used in the Peppol environment. The policies that apply to this BIS are the following:

8.1. Profiles and messages

All messages contains ProfileID and CustomizationID. ProfileID identifies what business process a given message is part of, and CustomizationID identifies the kind of message and the rules applied.

Profiles are connected to one business process, and may contain multiple document types. Valid document instances shall contain corresponding ProfileID and CustomizationID.

CustomizationID is a string without spaces. The list below contains spaces in CustomizationID to make them easier to read. Make sure to remove any spaces before use.

8.2. Customization and Profile identifiers

In the table below you will find the values to be used as the specification identifier and the business process type for this profile

Type Element cbc:CustomizationID Element cbc:ProfileID

Order Agreement (Trdm110)

urn:fdc:peppol.eu:poacc:trns:order_agreement:3

urn:fdc:peppol.eu:poacc:bis:order_agreement:3

8.3. Namespaces

The order agreement data model is in this Peppol BIS bound to the UBL 2.1 of the order response document type UBL Order Response 2.1. The target namespace for the UBL-OrderResponse-2.1 is:

urn:oasis:names:specification:ubl:schema:xsd:OrderResponse-2