EHF Order Agreement 3.0

This document describes the new version of EHF Order Agreement (called "EHF Orderforslag" in Norwegian). The document is part of Norwegian Agency for Public and Financial Management (DFØ) standardization work related to electronic commerce.

1. 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.2 (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.

1.1. Prerequisites

The following are prerequisites for this EHF:

A buyer has purchased goods or services from the seller by any means.
The seller has to be registered in the buyer system with information as contact information and identifiers used for other EHF transaction e.g. EHF order and invoice (GLN, Organization number…)

1.2. Scope

The intended scope for this EHF includes business-to-government (B2G) and business-to-business (B2B) relationships. Although the EHF 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 EHF 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 EHF are described in Process and typical use cases.

This is an auxiliary EHF intended to complement the primary ordering EHFs, such as Peppol EHF 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.

1.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 EHF.

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.

1.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.

1.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.

1.6. Interoperability

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

Legal Interoperability
- Legal:
  - In implementations supporting public sector buyers, the use of the Punch out EHF has to be monitored in order to secure that the buyers act in line with EU procurement directives.
Organizational interoperability
- Organization (Organization/Business):
  - This Peppol EHF supports B2B and B2G.
  - This Peppol EHF supports cross border, regional and domestic ordering in EU and EEA.
  - This Peppol EHF can function as a component in an EDI agreement within a trading community.
  - This Peppol EHF 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 EHF 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.
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 EHF.
    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.
Technical interoperability
- Technical Interaction (Process and semantic implementation):
  - Binding to OASIS UBL 2.2, see UBL 2.2
  - 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 EHF. Not supported.

2. Process and typical use cases

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

2.1. Process flow

The order agreement process flow can be described as follows:

Possible start positions:

A Buyer makes a purchase of goods or services from the Seller.
A Seller reports one or more accumulated purchases made under a framework agreement to the Buyer.

End positions:

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.

2.2. Business process Diagram

2.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.

2.3. Business process Diagram

2.3.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.

Figure 1. BPMN legend

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

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.

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

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

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.
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 EHF.

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.

2.5. 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.

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.
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 EHF.
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.

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

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.
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 EHF.
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.

2.7. 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.

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.
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 EHF.
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.

2.8. 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.

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.
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.

3. Description of selected parts of the order agreement message

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

3.1. Parties

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

3.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 EHF 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>

3.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 EHF 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>

3.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 EHF 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>

3.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 EHF 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>

3.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 EHF 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>

3.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>

3.4. Attachments on header level

Non-XML documents can be sent as attachments to the Peppol EHF 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 EHF 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>

3.5. Attachments and document references on line level

Non-XML documents can be sent as attachments to the Peppol EHF 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 EHF 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_EHF_28a-101.pdf</cbc:URI>
    </cac:ExternalReference>
  </cac:Attachment>
</cac:ItemSpecificationDocumentReference>

3.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 EHF 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>

3.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 EHF Order Agreement message

<cac:Item>
  <cbc:Description>Description of the item</cbc:Description>
  <cbc:Name>Item name</cbc:Name>

3.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 EHF. 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>

3.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>

3.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>

3.11. Quantities and units

Various Quantities and Units can be stated in the Peppol EHF 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 .

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>

3.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>

3.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 [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)\$

3.14. TAX information (TAX)

The chapters below describe the different TAX informations that can be provided in this EHF. 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 [vat-calc] for detailed explanation and example on how to perform the calculations for TAX Breakdown.

3.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	Value must identify the correct tax type. For example VAT, GST or sales tax.

3.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

Appendix A: UBL 2.2

This implementation guide builds on UBL 2.2 Schemas, available from OASIS.

These schemas are used when performing syntax validation.

Please see the homepage for information about the standard or further resources available.

Appendix B: 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.

B.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.

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.

B.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.

B.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

Component

Use

Primitive Type

Example

Content

Mandatory

Decimal

10000.25

B.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

Component

Use

Primitive Type

Example

Content

Mandatory

Decimal

10000.1234

B.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

Component

Use

Primitive Type

Example

Content

Mandatory

Decimal

34.7812

B.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

Component

Use

Primitive Type

Example

Content

Mandatory

Decimal

10000.1234

B.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

Component

Use

Primitive Type

Example

Content

Mandatory

String

Abc123

B.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

B.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

B.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

B.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

B.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

Component

Use

Primitive Type

Example

Content

Mandatory

String

5% allowance when paid within 30 days

B.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

Component

Use

Primitive Type

Example

Content

Mandatory

Binary

QmFzZTY0IGNvbnRlbnQgZXhhbXBsZQ==

Mime Code

Mandatory

String

image/jpeg

Filename

Mandatory

String

drawing5.jpg

B.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	String	true

Component

Use

Primitive Type

Example

Content

Mandatory

String

true