Export definition

Explore the comprehensive XML definition of cXML invoices

Proactis uses the cXML standard to generate invoices and send these your application endpoint.

Basic invoice example

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/1.2.051/InvoiceDetail.dtd">
<cXML payloadID="[email protected]" timestamp="2022-01-13T01:17:00-01:17" xml:lang="en-US">
   <Header>
      <From>...</From>
      <To>...</To>
      <Sender>...</Sender>
   </Header>
   <Request deploymentMode="test">
      <InvoiceDetailRequest>
         <InvoiceDetailRequestHeader invoiceID="2019-01" purpose="debitMemo" operation="new" invoiceDate="2019-11-01T11:00">
            <InvoiceDetailHeaderIndicator isVatRecoverable="yes"/>
            <InvoiceDetailLineIndicator isTaxInLine="yes"/>
            <InvoicePartner>...</InvoicePartner>
            <InvoiceDetailShipping>...</InvoiceDetailShipping>
            <PaymentTerm></PaymentTerm>
            <PaymentInformation paymentNetDueDate="2019-11-30T11:00:00+01:00"/>
            <Comments>...</Comments>
            <IdReference identifier="ref1" domain="Extra ref 1"/>
            <Extrinsic name="ProactisInvoiceNumber">INV100000012</Extrinsic>
            <Extrinsic name="ProactisStatus">Cleared</Extrinsic>
            <Extrinsic name="ProactisCreationDate">2019-11-18T12:45:48</Extrinsic>
            <Extrinsic name="ProactisProcessedDate">2022-01-13</Extrinsic>
         </InvoiceDetailRequestHeader>
         <InvoiceDetailOrder>
                <InvoiceDetailOrderInfo>
                    <OrderReference orderID="[Purchase Order Number]"/>
                </InvoiceDetailOrderInfo>
                <InvoiceDetailItem invoiceLineNumber="1" quantity="15.0000">...</InvoiceDetailItem>
                <InvoiceDetailItem invoiceLineNumber="2" quantity="1.0000">...</InvoiceDetailItem>
            </InvoiceDetailOrder>
            <InvoiceDetailSummary>
                <SubtotalAmount>...</SubtotalAmount>
                <Tax>...</Tax>
                <GrossAmount>...</GrossAmount>
                <NetAmount>...</NetAmount>
            </InvoiceDetailSummary>
        </InvoiceDetailRequest>
    </Request>
</cXML>

Header

The invoice starts with the Header which can used to authenticate the message and understand which supplier this has been sent from.

<Header>
   <From>
      <Credential domain="NetworkId">
         <Identity>SUPPLIER IDENTIFIER</Identity>
      </Credential>
   </From>
   <To>
      <Credential domain="NetworkId">
         <Identity>CUSTOMER IDENTIFIER</Identity>
      </Credential>
   </To>
   <Sender>
      <Credential domain="NetworkId">
         <Identity>Proactis</Identity>
      </Credential>
      <UserAgent>proactis-eu-agent</UserAgent>
   </Sender>
</Header>

The From Credential domain attribute and Identity element are used to identify the supplier who sent the invoice.

The To Credential domain attribute and Identity element are used to identify the customer the invoice has been sent to. This is the Proactis organisation identifier.

The Sender Credential domain attribute and Identity element are used to identify the system that has sent the invoice. The SharedSecret element remains empty.

Request

The Request element contains the the InvoiceDetailRequest and shows if this invoice has been sent from a test or production environment.

UAT environment

<Request deploymentMode="test">

Production environment

<Request deploymentMode="production">

InvoiceDetailRequestHeader

This contains attributes for the invoiceID, purpose, operation and invoiceDate.

<InvoiceDetailRequestHeader invoiceID="2019-01" purpose="debitMemo" operation="new" invoiceDate="2019-11-01T11:00">

The invoiceID is the invoice reference, usually the supplier issued invoice number.

The purpose depends on the type of invoice:

• debitMemo : debit invoice
• creditMemo : credit invoice
• standard : reversed billing of proforma invoice

The operation will always be "new"

The invoiceDate is the supplier invoice data. This is in the format: YYYY-MM-DD'T'hh:mm.

InvoicePartner

The InvoicePartner elements contains (address) information of the creator, billTo of remitTo.

<InvoicePartner>
   <Contact role="solver">
      <Name xml:lang="en-US">Solver Name</Name>
   </Contact>
</InvoicePartner>

<InvoicePartner>
   <Contact role="payer">
      <Name xml:lang="en-US">Payer Name</Name>
   </Contact>
</InvoicePartner>

<InvoicePartner>
   <Contact role="billTo">
      <Name xml:lang="en-US"></Name>
   </Contact>
</InvoicePartner>

InvoicePartner/Supplier

The remitTo Contact contains IdReference elements which contain the VAT ID of the supplier, but also the bank account information. Depending on the bank account type there are various options.

SEPA

A SEPA account consists of an IdReference with domain "ibanID" and an identifier value of the iban number. An IdReference with domain "swiftId" can be present if a swift id is defined.

<InvoicePartner>
   <Contact role="remitTo">
      <Name xml:lang="en-US">SupplierName</Name>
      <IdReference identifier="123456780" domain="ibanID"/>
      <IdReference identifier="123456780" domain="swiftId"/>
      <IdReference identifier="123456780" domain="vatID"/>
   </Contact>
</InvoicePartner>

SEPA G-account

A SEPA G-account consists of an IdReference with domain "ibanGAccountID" and an identifier value of the G account number. An IdReference with domain "swiftId" can be present if a swift id is defined.

<InvoicePartner>
   <Contact role="remitTo">
      <Name xml:lang="en-US">SupplierName</Name>
      <IdReference identifier="123456780" domain="ibanGAccountID"/>
      <IdReference identifier="123456780" domain="swiftId"/>
      <IdReference identifier="123456780" domain="vatID"/>
   </Contact>
</InvoicePartner>

G-account

A G account consists of an IdReference with domain "bankGAccountID" and an identifier value of the G account number.

<InvoicePartner>
   <Contact role="remitTo">
      <Name xml:lang="en-US">SupplierName</Name>
      <IdReference identifier="123456780" domain="bankGAccountID"/>
      <IdReference identifier="123456780" domain="vatID"/>
   </Contact>
</InvoicePartner>

Foreign account

A foreign account consists of an IdReference with domain "bankForeignAccountID" and an identifier value of the foreign account number. An IdReference with domain "swiftId" can be present if a swift id is defined.

<InvoicePartner>
   <Contact role="remitTo">
      <Name xml:lang="en-US">SupplierName</Name>
      <IdReference identifier="123456780" domain="bankForeignAccountID"/>
      <IdReference identifier="123456780" domain="swiftId"/>
   </Contact>
</InvoicePartner>

Other

An account defined as "Other" consists of an IdReference with domain "bankAccountID" and identifier value of the account number. An IdReference with domain "swiftId" can be present if a swift id is defined.

<InvoicePartner>
   <Contact role="remitTo">
      <Name xml:lang="en-US">SupplierName</Name>
      <IdReference identifier="123456780" domain="bankAccountID"/>
      <IdReference identifier="123456780" domain="swiftId"/>
   </Contact>
</InvoicePartner>

Payment Information

The PaymentTerm and PaymentInformation elements contain information about the payment terms.

<PaymentTerm payInNumberOfDays="3">
   <Discount>
      <DiscountPercent percent="5.0000"/>
   </Discount>
</PaymentTerm>

<PaymentInformation paymentNetDueDate="2019-11-30T11:00:00+01:00"/>

The PaymentTerm payInNumberOfDays attribute indicates the invoice must be paid in a certain number of days after the invoice effective date.

The DiscountPercent element contains the percentage of the discount term. The discount rate applies if the invoice total is paid within the time specified by payInNumberOfDays.

The PaymentInformation element is the data on which the invoice must be paid.

Extra References

Invoices in Proactis can have up till 4 invoice references.

<IdReference identifier="ref1" domain="Reference 1 value"/>
<IdReference identifier="ref2" domain="Reference 2 value"/>
<IdReference identifier="ref3" domain="Reference 3 value"/>
<IdReference identifier="ref4" domain="Reference 4 value"/>

The identifier attribute contains the name of the invoice references as configured in Proactis. The domain is the value of the invoice reference.

Extrinsics

Extrinsics are additional elements that can be included to extend the cXML standard. Proactis uses the Extrinsics for various attributes.

<Extrinsic name="ProactisInvoiceNumber">INV100000012</Extrinsic>
<Extrinsic name="ProactisStatus">Cleared</Extrinsic>
<Extrinsic name="ProactisCreationDate">2019-11-18T12:45:48</Extrinsic>
<Extrinsic name="ProactisApprovalDate">2020-05-22T12:03:04+02:00</Extrinsic>
<Extrinsic name="ProactisProcessedDate">2022-01-13</Extrinsic>

The ProactisInvoiceNumber Extrinsic contains the Proactis generated invoice number.

The ProactisStatus Extrinsic contains the current status of the invoice in Proactis. The following statuses are available: Concept, Exception, For Approval, Processed, Cleared, Archived, On Hold, For Validation, Deleted, For Evaluation, Sent or Rejected.

The ProactisCreationDate Extrinsic stores the date/time on which the invoice was created or imported in Proactis.

The ProactisApprovalDate Extrinsic stores the date/time on which the invoice had its last approval.

The ProactisProcessedDate Extrinsic stores the date/time on which the invoice was moved to the Cleared status. The Extrinsic will have no value in case the invoice has not yet been processed.

InvoiceDetailOrder

This contains the InvoiceDetailOrderInfo element which provides a reference to the matching purchase order.

<InvoiceDetailOrderInfo>
   <OrderReference orderID="12345678" orderDate="2019-11-18T12:45:31">
      <DocumentReference payloadID="[email protected]"/>
   </OrderReference>
   <SupplierOrderInfo orderID="12345678"/>
</InvoiceDetailOrderInfo>

The OrderReference element contains two attributes. The orderID attribute is the Proactis purchase order number. The orderDate attribute is the creation date/time of the purchase order.

Each InvoiceDetailOrder will contain one or more InvoiceDetailItem elements. These contain more information about the lines listed on the invoice.

<InvoiceDetailItem invoiceLineNumber="1" quantity="15.0000">
   <UnitOfMeasure>PCE</UnitOfMeasure>
   <UnitPrice>
      <Money currency="USD">55.6100</Money>
   </UnitPrice>
   <InvoiceDetailItemReference lineNumber="1">
      <ItemID>
         <SupplierPartID>Product id</SupplierPartID>
      </ItemID>
      <Description type="name" xml:lang="en-US">Product name</Description>
   </InvoiceDetailItemReference>
   <SubtotalAmount>
      <Money currency="USD">834.1500</Money>
   </SubtotalAmount>
   <Tax>
      <Money currency="USD">175.1715</Money>
      <Description xml:lang="en-US"/>
      <TaxDetail category="VAT" percentageRate="21.0000" taxRateType="4">
         <TaxAmount>
            <Money currency="USD">175.1715</Money>
         </TaxAmount>
      </TaxDetail>
   </Tax>
   <GrossAmount>
      <Money currency="USD">1009.3215</Money>
   </GrossAmount>
   <NetAmount>
      <Money currency="USD">834.1500</Money>
   </NetAmount>
   <Distribution>
      <Accounting name="CostCoding">
         <Segment type="DepartmentId" id="A-100" description="Department name"/>
         <Segment type="CostCenterType" id="CTId" description="CostCenter type name"/>
         <Segment type="CostCenterId" id="CC050" description="CostCenter name"/>
         <Segment type="CostCenterErpId" id="CC050" description="CostCenter name"/>
         <Segment type="CostAccountType" id="CATName" description="CostAccount type description"/>
         <Segment type="CostAccountId" id="ca-015" description="CostAccount name"/>
         <Segment type="CostAccountErpId" id="ca-015" description="CostAccount name"/>
         <Segment type="Objectcode" id="A50" description="A50 dimension"/>
      </Accounting>
      <Charge>
         <Money currency="USD">1009.3215</Money>
      </Charge>
   </Distribution>
   <Extrinsic name="Intention">Birthday John Doe</Extrinsic>
   <Extrinsic name="ProactisReceiptNumber">Rec_1000002357</Extrinsic>
   <Extrinsic name="ProactisInvoicedCompletely">true</Extrinsic>
</InvoiceDetailItem>

InvoiceDetailItem

The invoiceLineNumber attribute is the invoice line number. The quantity attribute is the quantity for the invoice line being invoiced.

<InvoiceDetailItem invoiceLineNumber="1" quantity="15.0000">

UnitOfMeasure

The UnitOfMeasure element contains the Unit Of Measure (UOM) the line was invoiced in. This usually matches the UOM for the purchase order line.

<UnitOfMeasure>PCE</UnitOfMeasure>

UnitPrice

The UnitPrice element contains the Money element. The Money element has a currency attribute and the per unit price for the line.

<UnitPrice>
   <Money currency="USD">55.6100</Money>
</UnitPrice>

InvoiceDetailItemReference

The InvoiceDetailItemReference contains the lineNumber attribute, this is the reference that matches up the invoice line with the purchase order line.

The ItemID element contains the SupplierPartID element which is the product code for the line.

The Description element contains the description for the line.

<InvoiceDetailItemReference lineNumber="1">
   <ItemID>
      <SupplierPartID>Product id</SupplierPartID>
   </ItemID>
   <Description type="name" xml:lang="en-US">Product name</Description>
</InvoiceDetailItemReference>

SubtotalAmount

The Subtotal element contains the Money element. The Money element has a currency attribute and the subtotal for the line.

This should be calculated based on UnitPrice x Quantity = SubtotalAmount.

<SubtotalAmount>
   <Money currency="USD">834.1500</Money>
</SubtotalAmount>

Tax

This is the Tax information for the item.

<Tax>
   <Money currency="USD">175.1715</Money>
   <Description xml:lang="en-US"/>
   <TaxDetail category="VAT" percentageRate="21.0000" taxRateType="4">
      <TaxAmount>
         <Money currency="USD">175.1715</Money>
      </TaxAmount>
   </TaxDetail>
</Tax>

The Money element total amount of tax for the item.

The category attribute is the type of tax that is being applied.

The percentageRate attribute is the tax rate being applied.

The taxRateType is a Proactis specific value assigned to the type of tax.

The TaxAmount element is the amount of tax for the TaxableAmount.

GrossAmount & NetAmount

The GrossAmount and NetAmount elements contain a Money element and currency attribute. This contains the gross and net amount for the invoice line.

<GrossAmount>
   <Money currency="USD">1009.3215</Money>
</GrossAmount>

<NetAmount>
   <Money currency="USD">834.1500</Money>
</NetAmount>

Distribution

The Distribution contains the cost coding information assigned to the item.

<Distribution>
   <Accounting name="CostCoding">
      <Segment type="DepartmentId" id="A-100" description="Department name"/>
      <Segment type="CostCenterType" id="CTId" description="CostCenter type name"/>
      <Segment type="CostCenterId" id="CC050" description="CostCenter name"/>
      <Segment type="CostCenterErpId" id="CC050" description="CostCenter name"/>
      <Segment type="CostAccountType" id="CATName" description="CostAccount type description"/>
      <Segment type="CostAccountId" id="ca-015" description="CostAccount name"/>
      <Segment type="CostAccountErpId" id="ca-015" description="CostAccount name"/>
      <Segment type="Objectcode" id="A50" description="A50 dimension"/>
   </Accounting>
   <Charge>
      <Money currency="USD">1009.3215</Money>
   </Charge>
</Distribution>

The Segment with the type DepartmentId contains the department ID linked to the item.

The Segment with the type CostCenterId, CostCenterType and CostCenterErpId contain information on the cost center.

The Segment with the type CostAccountId, CostAccountType and CostAccountErpId contain information on the cost account.

Cost Dimensions are added as separate Segment elements. The type being the name of the parent dimension.

Smart Forms

Extrinsic elements are added for Smart Form fields. Fields that can be used to add customer specific information.

<Extrinsic name="Intention">Birthday John Doe</Extrinsic>

Contract reference

Two Extrinsic elements will be added in case the product is related to a contract.

<Extrinsic name="ProactisContractNumber">C1000000665</Extrinsic>
<Extrinsic name="ProactisContractReference">IT Support</Extrinsic>

Receipts

An Extrinsic element with the name ProactisReceiptNumber is added for each receipt that has been created for this PO line.

<Extrinsic name="ProactisReceiptNumber">Rec_1000002217</Extrinsic>

Timesheets

And Extrinsic element with the name ProactisTimesheet will be added to workforce related invoices. Each invoice lines will contain one or more timesheets which were created for the order.

<Extrinsic name="ProactisTimesheet">TS1000123_00(34)</Extrinsic>

Completely invoiced

For PO-invoices a new Extrinsic has been added which specifies the status of the underlying order. In case the order has been completely invoiced, this Extrinsic will have a value true.

<Extrinsic name="ProactisInvoicedCompletely">true</Extrinsic>

InvoiceDetailSummary

The InvoiceDetailSummary element contains totals used validate the invoice.

<InvoiceDetailSummary>
   <SubtotalAmount>
      <Money currency="USD">834.1500</Money>
   </SubtotalAmount>
   <Tax>
      <Money currency="USD">175.1715</Money>
      <Description xml:lang="en-US">VAT Summary</Description>
   </Tax>
   <GrossAmount>
      <Money currency="USD">308.6400</Money>
   </GrossAmount>
   <NetAmount>
      <Money currency="USD">1009.3215</Money>
   </NetAmount>
</InvoiceDetailSummary>

SubtotalAmount

The SubtotalAmount element contains the Money element. The Money element has a currency attribute and the sum total for all lines on the invoice. This should be calculated based on the sum of the subtotal amounts from each line.

<SubtotalAmount>
   <Money currency="USD">834.1500</Money>
</SubtotalAmount>

Tax

The Tax element contains the Money element. The Money element has a currency attribute and the sum total of tax for all lines on the invoice. The Description element contains a default value.

<Tax>
   <Money currency="USD">175.1715</Money>
   <Description xml:lang="en-US">VAT Summary</Description>
</Tax>

GrossAmount & NetAmount

The GrossAmount and NetAmount elements contain the Money element. The Money element has a currency attribute and the amount for the invoice.

<GrossAmount>
   <Money currency="USD">308.6400</Money>
</GrossAmount>
<NetAmount>
   <Money currency="USD">1009.3215</Money>
</NetAmount>

Common cXML Elements

The tables show some examples on where to find common fields used from the Header and Item levels.

Header level

Detail	Path	Example
Supplier	cXML/Header/From/Credential[@domain="NetworkId"]/Identity	SUPPLIER IDENTIFIER
Customer	cXML/Header/To/Credential[@domain="NetworkId"]/Identity	CUSTOMER IDENTIFIER
Environment	cXML/Request/@deploymentMode	test
Proactis Invoice Number	cXML/Request/InvoiceDetailRequest/InvoiceDetailRequestHeader/Extrinsic[name="ProactisInvoiceNumber"]	INV100000012
Supplier Invoice Number	cXML/Request/InvoiceDetailRequest/InvoiceDetailRequestHeader/@invoiceID	2019-01
Invoice Type	cXML/Request/InvoiceDetailRequest/InvoiceDetailRequestHeader/@purpose	debitMemo
Supplier Invoice Date	cXML/Request/InvoiceDetailRequest/InvoiceDetailRequestHeader/@invoiceDate	2019-11-01T11:00
Bank Account	cXML/Request/InvoiceDetailRequest/InvoiceDetailRequestHeader/InvoicePartner/Contact[role="remitTo"]/IdReference	123456780
Invoice Status	cXML/Request/InvoiceDetailRequest/InvoiceDetailRequestHeader/Extrinsic[name="ProactisStatus"]	Cleared
Gross Amount	cXML/Request/InvoiceDetailRequest/InvoiceDetailSummary/GrossAmount/Money	308.6400
Net Amount	cXML/Request/InvoiceDetailRequest/InvoiceDetailSummary/NetAmount/Money	1009.3215
Tax Amount	cXML/Request/InvoiceDetailRequest/InvoiceDetailSummary/Tax/Money	175.1715

Item Level

Detail	Path	Example
Order Reference	cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder[*]/InvoiceDetailOrderInfo/OrderReference/@orderID	12345678
Line Number	cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder[*]/InvoiceDetailItem[*]/@invoiceLineNumber	1
Quantity	cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder[*]/InvoiceDetailItem[*]/@quantity	15.0000
Unit Price	cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder[*]/InvoiceDetailItem[*]/UnitPrice/Money	Product id
Item Code	cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder[*]/InvoiceDetailItem[*]/InvoiceDetailItemReference/ItemID/SupplierPartID	Product id
Sub Total Amount	cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder[*]/InvoiceDetailItem[*]/SubtotalAmount/Money	834.1500
Tax	cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder[*]/InvoiceDetailItem[*]/Tax/Money	175.1715
Department ID	cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder[*]/InvoiceDetailItem[*]/Distribution/Accounting/Segment[type="DepartmentId"]	A-100
Cost Center ID	cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder[*]/InvoiceDetailItem[*]/Distribution/Accounting/Segment[type="CostCenterId"]	CC050
Cost Account ID	cXML/Request/InvoiceDetailRequest/InvoiceDetailOrder[*]/InvoiceDetailItem[*]/Distribution/Accounting/Segment[type="CostAccountId"]	ca-015