Back
XML Specifications

Modified on 2014/11/24 16:48 by jdibble Categorized as Uncategorized
{s:Breadcrumbs
| page_name = XML Specification
}
==XML Specifications==
<div id="page-menu">
===Quick Links===
* [Integration-Guide|Overview & Posting Orders]
* [XML-Specifications | XML Specifications]
** [#_structure|XML Structure]
** [#_sample-set|Sample XML Set]
** [#_xml-content|XML Elements and Content]
** [Ship-To-Store Order XML | Ship-To-Store Order XML]
** [Moderated Orders XML | Moderated Order XML]
* [Product-Specifications | Product Specifications and Details]
* [Shipping | Shipping and the EZP Shipping Calculator]
* [Event-Notifications | Event Notifications, Order Status, and Errors]
* [Testing | Testing]
* [Code-Sample | Code Sample Library]
</div><h2>[anchor|#overview]XML Structure</h2>As mentioned earlier, EZP requires a particular XML format for partners who are not using the ezp ecommerce module. The following is an overview of the ezprints order XML standard. A summary of the order structure is provided, along with an example of XML elements in an order, and a description of each element. Your EZP Integration Manager can also provide an the XML schema in the form of a .XSD file, if desired.

A high level structure of the EZP Order XML consists of these key elements:
* Orders
* Images
* Order Session
* Vendor
* Customer
* Order
* Shipping Address
* Orderline

The format is designed to accommodate multiple orders per ordersession if desired (e.g. your application or website customer places one order to be sent to her, one order to be sent to grandma at another address, and you bundle both orders into one ordersession). However, it is most common to send ezprints one order per ordersession. If you send one order per ordersession, it is recommended that your ordersessionID be the same as your internal orderID for clarity in reporting. Recall that you pass your orderID in the order XML post statement.

For partners who are not using the ezp Builder, the orderline element is a unique combination of Image + Product SKU. You will pass a quantity with the orderline. The challenge for some partners is if you offer a "package" of products that in your system is one productid (e.g. your product009 is a set of 2 4x6 prints, 1 8x10 and 1 sheet of address labels), it needs to be broken down into unique EZP productids per orderline. This is a high level sample of the images and orderlines structures:

<pre>
Image1
Image2
Image3

Orderline1 = Image1 + ProductSKU1, quantity = 1
Orderline2 = Image1 + ProductSKU2, quantity = 2
Orderline3 = Image2 + ProductSKU2, quantity = 1
Orderline4 = Image3 + ProductSKU1, quantity = 2
Orderline5 = Image3 + ProductSKU4, quantity = 1, Etc.
</pre>

For partners using the ezp Builder, the orderline element in the XML is slightly different. These differences are explained in the [Builder-Commerce-Guide#postingXML | ezp product builders section]. The rest of the XML will be the same, regardless of whether or not you are using the ezp product builders.
===[anchor|#sample-set]Sample XML Set===

Listed below is an example of an XML order.

<pre><esc>
<?xml version="1.0" encoding="UTF-8"?>
<orders partnerid = "xxxxx" version = "1">
    <images>
        <uri id="3" title="Logo">http://www.ezprints.com/images/logo.jpg</uri>
        <uri id="5" title="My Photo">http://www.ezprints.com/images/0/0_5.jpg</uri>
        <uri id="6" title="A  Photo">http://www.ezprints.com/images/0/123.jpg</uri>
    </images>
    <ordersession>
        <sessionid>1234</sessionid>
        <vendor logoimageid = "3">
            <name>MyCompanyName</name>
            <address1>123 Any St.</address1>
            <address2>Apartment 3</address2>
            <city>Anytown</city>
            <state>PA</state>
            <zip>12345</zip>
            <countrycode>USA</countrycode>
            <phone>303-555-1212</phone>
            <email>jane@host.com</email>
            <url>www.ezprints.com</url>
        </vendor>
        <customer>
            <customerid>1234</customerid>
            <title>Ms</title>
            <firstname>Jane</firstname>
            <lastname>Doe</lastname>
            <address1>123 Any St.</address1>
            <address2>Apartment 3</address2>
            <city>Anytown</city>
            <state>PA</state>
            <zip>12345</zip>
            <countrycode>USA</countrycode>
            <phone>303-555-1212</phone>
            <email>jane@host.com</email>
        </customer>
        <order>
            <orderid>1234</orderid>
            <shippingaddress>
                <title>Ms</title>
                <firstname>Jane</firstname>
                <lastname>Doe</lastname>
                <address1>456 Another St.</address1>
                <address2>Unit D</address2>
                <city>Anothertown</city>
                <state>ON</state>
                <zip>B6B-4G3</zip>
                <countrycode>USA</countrycode>
                <phone>301-555-1212</phone>
                <email>jo@hots.com</email>
            </shippingaddress>
            <shippingmethod>FC</shippingmethod>
            <orderline productid = "10050" imageid = "5">
                <description>5x7 Glossy Print</description>
                <productprice>1.95</productprice>
                <quantity>1</quantity>
                <position>fit</position>
            </orderline>
            <producttotal>1.95</producttotal>
            <shippingprice>5.95</shippingprice>
            <tax>0.00</tax>
            <ordertotal>1.95</ordertotal>
        </order>
        <producttotal>1.95</producttotal>
        <shippingtotal>5.95</shippingtotal>
        <taxtotal>0.00</taxtotal>
        <total>7.90</total>
    </ordersession>
</orders>
</esc></pre>

===[anchor|#xml-content]XML Elements and Content===

Listed below is a description of all of the XML elements and associated content. Many optional fields not contained in the above XML spec have been included.

{| cellspacing="0" cellpadding="2"
! Element Name !! Child Name !! Element or Attribute? !! Required !! Element Cardinality !! Description<span style="display: block;width: 200px;"></span>
|-
| style="background-color:#ff99cc;" | orders 
| <!-- empty -->
| Root element 
| Required 
| Root element - one only 
| The Orders element has a required partnerid attribute that will be assigned by ezprints. There is also a required version attribute. The current version number is 1. The Orders element normally contains only 1 ordersession child. The following items are children of an Order element.
|-
| style="background-color:#ff99cc;" | orders 
| style="background-color:#ffcc99;" | images 
| Element 
| Required 
| 1 or more 
| The Images element contains n uri children. This section provides a listing of a images used in the document. The URL?s submitted in the XML do not need to be URL-encoded. If any XML reserved characters are used in the URL, they must be replaced by the proper escape sequence. For example, the URL <a href="http://www.foo.com?id=1&amp;name=test" target="_blank">http://www.foo.com?id=1&amp;name=test</a> would need to be escaped to: <a href="http://www.foo.com?id=1&amp;name=test" target="_blank">http://www.foo.com?id=1&amp;name=test</a>
|-
| style="background-color:#ff99cc;" | orders 
| style="background-color:#ffcc99;" | ordersession
| Element 
| Required 
| Normally only 1 
| The ordersession element normally contains 1 order child. There is one customer per ordersession.
|-
| style="background-color:#ff99cc;" | orders 
| partnerid
| Attribute 
| Required 
| Only 1 
| Your partner ID as assigned by ezprints
|-
| style="background-color:#ff99cc;" | <!-- empty -->
| version
| Attribute 
| Required 
| Only 1 
| current version = <esc>"1"</esc>
|-
! Element Name !! Child Name !! Element or Attribute? !! Required !! Element Cardinality !! Description<span style="display: block;width: 200px;"></span>
|-
| style="background-color:#ffcc99;" | images 
| <!-- empty -->
| Element 
| Required 
| Only 1
| The Images element contains n uri children. This section provides a listing of images used in the document. The URL's submitted in the XML do not need to be URL-encoded. If any XML reserved characters are used in the URL, they must be replaced by the proper escape sequence. For example, the URL <a href="http://www.foo.com?id=1&amp;name=test" target="_blank">http://www.foo.com?id=1&amp;name=test</a> would need to be escaped to: <a href="http://www.foo.com?id=1&amp;name=test" target="_blank">http://www.foo.com?id=1&amp;name=test</a>
|-
| style="background-color:#ffcc99;" | images 
| style="background-color:#ffcc00;" | uri
| Element 
| Required 
| <!-- empty -->
| The content of this element should contain the URL pointing to a high resolution image.
|-
| style="background-color:#ffcc00;" | uri 
| id
| Attribute
| Required 
| <!-- empty -->
| The images id is referenced in Orderlines element, e.g. this image is to go on this product. The uri id can contain numbers or letters.
|-
| style="background-color:#ffcc00;" | uri 
| title
| Attribute
| Optional
| <!-- empty -->
| Image title. 40 characters of the image title will appear as backprint on any RA4 print.
|-
! Element Name !! Child Name !! Element or Attribute? !! Required !! Element Cardinality !! Description<span style="display: block;width: 200px;"></span>
|-
| style="background-color:#ffcc99;" | ordersession
| <!-- empty -->
| Element
| Required
| Normally only 1
| The ordersession element normally contains 1 order child. There is one customer per ordersession.
|-
| style="background-color:#ffcc99;" | ordersession
| style="background-color:#ffff99;" | order
| Element
| Required
| One or more
| The Order element represents an order to be shipped to a single address, and therefore contains a required shippingaddress and n orderline children.
|-
| style="background-color:#ffcc99;" | ordersession
| style="background-color:#ffff99;" | vendor
| Element
| Required
| Only 1
| Use this element to specify the vendor/brand to be printed on the packing slip and index print. If included, the vendor element has a required logoimageid attribute. The children of the Vendor element are self-explanatory. The Name element is required. All other children are optional.
|-
| style="background-color:#ffcc99;" | ordersession
| style="background-color:#ffff99;" | customer
| Element
| Optional
| Only 1
| Partner's customer information (customer who placed the order). All children of the customer element are optional. Not used for any billing purposes.
|-
| style="background-color:#ffcc99;" | ordersession
| producttotal
| Element
| Optional
| Only 1
| Sum of all the retail producttotal elements in the ordersession order(s). Not visible on the work order.
|-
| style="background-color:#ffcc99;" | ordersession
| discounttotal
| Element
| Optional
| Only 1
| Sum of all the retail discount elements in the ordersession order(s). Not visible on the work order.
|-
| style="background-color:#ffcc99;" | ordersession
| shippingtotal
| Element
| Optional
| Only 1
| Sum of all the retail shippingprice elements in the ordersession order(s). Not visible on the work order.
|-
| style="background-color:#ffcc99;" | ordersession
| taxtotal
| Element
| Optional
| Only 1
| Sum of all the tax elements in the ordersession order(s). Not visible on the work order.
|-
| style="background-color:#ffcc99;" | ordersession
| total
| Element
| Optional
| Only 1
| Sum of retail producttotal, shippingprice, and taxtoal elements in ordersession order(s). Not visible on the work order.
|-
| style="background-color:#ffcc99;" | ordersession
| sessionid
| Element
| Recommended
| Only 1
| This is normally the same value as partner's orderid in the order element, and printed on the work order. The datatype is alphanumeric and has a maximum length of 50 characters.
|-
| style="background-color:#ffcc99;" | ordersession
| sessiondate
| Element
| Optional
| Only 1
| Partner's session date or order date.
|-
! Element Name !! Child Name !! Element or Attribute? !! Required !! Element Cardinality !! Description<span style="display: block;width: 200px;"></span>
|-
| style="background-color:#ffff99;" | order
| <!-- empty -->
| Element
| Required
| One or more
| The Order element contains a required shippingaddress and n orderline children.
|-
| style="background-color:#ffff99;" | order
| orderid
| Element
| Recommended
| <!-- empty -->
| This is the partner's order ID and is printed on the index print and the work order. The datatype is alphanumeric and has a maximum length of 50 characters. The orderid value is usually the same as the ordersession sessionid value. This facilitates lookup of an order using the partner order number if necessary.
|-
| style="background-color:#ffff99;" | order
| producttotal
| Element
| Optional
| <!-- empty -->
| Sum of all the retail productprice elements in the orderlines. Not visible on the work order.
|-
| style="background-color:#ffff99;" | order
| discount
| Element
| Optional
| <!-- empty -->
| Partner's discount amount they applied to customer's order (e.g. from a promotion code). Not visible on the work order.
|-
| style="background-color:#ffff99;" | order
| shippingprice
| Element
| Optional
| <!-- empty -->
| Partner's retail price for shipping method. Not visible on the work order.
|-
| style="background-color:#ffff99;" | order
| tax
| Element
| Optional
| <!-- empty -->
| Tax for this order. Not visible on the work order.
|-
| style="background-color:#ffff99;" | order
| ordertotal
| Element
| Optional
| <!-- empty -->
| Sum of retail producttotal, shippingprice, and tax. Not visible on the work order.
|-
| style="background-color:#ffff99;" | order
| comment
| Element
| Optional
| <!-- empty -->
| Use this element to place your marketing message to the customer on the right side of the work order/ packing slip. Maximum 500 characters.
|-
| style="background-color:#ffff99;" | order
| shippingmethod
| Element
| Required
| <!-- empty -->
| Code of shipping method. Valid shipping codes are provided by ezprints. Current codes are FC,PM,SD,ON 
|-
| style="background-color:#ffff99;" | order
| style="background-color:#ccffcc;" | orderline
| style="background-color:#ccffcc;" | Element
| Required
| One or more
| Each orderline element contains a product and an image. The product being ordered is defined by the required productid attribute. The imageid attribute corresponds to an id from the images node of the document. The product id values are defined by ezprints. A table of current product SKUs can be found in the Products Specifications Guide .
|-
| style="background-color:#ffff99;" | order
| style="background-color:#ccffcc;" | shippingaddress
| style="background-color:#ccffcc;" | Element
| Required
| Only 1
| Only 5 children of the &lt;shippingaddress&gt; are required: address1, city, state (US and Canada only), countrycode, and zip. address1 and address2 print on shipping labels and have a 35 character limit.<br/><br/>A link to valid state and country codes can be found in the Shipping section of this document.
|-
! Element Name !! Child Name !! Element or Attribute? !! Required !! Element Cardinality !! Description<span style="display: block;width: 200px;"></span>
|-
| style="background-color:#ffff99;" | vendor
| <!-- empty -->
| Element
| Required
| Only 1
| Use this element to specify the vendor/brand to be printed on the packing slip and index print. If included, the vendor element has an required logoimageid attribute. The children of the Vendor element are self-explanatory. The Name element is required. All other children are optional.
|-
| style="background-color:#ffff99;" | vendor
| logoimageid
| Attribute
| Optional
| Only 1
| The logoimageid specified here will print on the work order as a 3.3” wide x 2” high sticker. It prints smaller on an index print. If no logoimageid is specified in the Vendor element we will use the logo you provide to your Integration Manager.
|-
| style="background-color:#ffff99;" | vendor
| name
| Element
| Required
| Only 1
| <!-- empty -->
|-
| style="background-color:#ffff99;" | vendor
| address1
| Element
| Required
| Only 1
| <!-- empty -->
|-
| style="background-color:#ffff99;" | vendor
| address2
| Element
| Optional
| Only 1
| <!-- empty -->
|-
| style="background-color:#ffff99;" | vendor
| city
| Element
| Required
| Only 1
| <!-- empty -->
|-
| style="background-color:#ffff99;" | vendor
| state
| Element
| Required
| Only 1
| <!-- empty -->
|-
| style="background-color:#ffff99;" | vendor
| zip
| Element
| Required
| Only 1
| <!-- empty -->
|-
| style="background-color:#ffff99;" | vendor
| countrycode
| Element
| Required
| Only 1
| <!-- empty -->
|-
| style="background-color:#ffff99;" | vendor
| email
| Element
| Optional
| Only 1
| <!-- empty -->
|-
| style="background-color:#ffff99;" | vendor
| url
| Element
| Optional
| Only 1
| <!-- empty -->
|-
! Element Name !! Child Name !! Element or Attribute? !! Required !! Element Cardinality !! Description<span style="display: block;width: 200px;"></span>
|-
| style="background-color:#ffff99;" | customer
| <!-- empty -->
| Element
| Optional
| Only 1
| Partner's customer information (customer who placed the order). All children of the customer element are optional.
|-
| style="background-color:#ffff99;" | customer
| firstname
| Element
| Optional
| Only 1
| <!-- empty -->
|-
| style="background-color:#ffff99;" | customer
| lastname
| Element
| Optional
| Only 1
| <!-- empty -->
|-
| style="background-color:#ffff99;" | customer
| companyname
| Element
| Optional
| Only 1
| 50 character limit.
|-
| style="background-color:#ffff99;" | customer
| address1
| Element
| Optional
| Only 1
| <!-- empty -->
|-
| style="background-color:#ffff99;" | customer
| address2
| Element
| Optional
| Only 1
| <!-- empty -->
|-
| style="background-color:#ffff99;" | customer
| city
| Attribute
| Optional
| Only 1
| <!-- empty -->
|-
| style="background-color:#ffff99;" | customer
| state
| Attribute
| Optional
| Only 1
| <!-- empty -->
|-
| style="background-color:#ffff99;" | customer
| zip
| Attribute
| Optional
| Only 1
| <!-- empty -->
|-
| style="background-color:#ffff99;" | customer
| countrycode
| Attribute
| Optional
| Only 1
| <!-- empty -->
|-
| style="background-color:#ffff99;" | customer
| phone
| Attribute
| Optional
| Only 1
| 30 character limit.
|-
| style="background-color:#ffff99;" | customer
| email
| Attribute
| Optional
| Only 1
| <!-- empty -->
|-
! Element Name !! Child Name !! Element or Attribute? !! Required !! Element Cardinality !! Description<span style="display: block;width: 200px;"></span>
|-
| style="background-color:#ccffcc;" | Orderline
| <!-- empty -->
| Element
| Required
| One or more
| Each orderline element contains a product and an image. The product being ordered is defined by the required productid attribute. The imageid attribute corresponds to an id from the images node of the document. The product id values are defined by ezprints. A table of current products id’s can be found in the Products Specifications. The children are described below.
|-
| style="background-color:#ccffcc;" | Orderline
| affiliatekey
| Element
| Optional
| Only 1
| You can specify an affiliatekey to assign a number to a specific orderline. This affiliatekey will be included in event notifications that describe specific orderlines.
|-
| style="background-color:#ccffcc;" | Orderline
| imageid
| Attribute
| Required
| Only 1
| Refers to an image listed in the <esc><images></esc> element.
|-
| style="background-color:#ccffcc;" | Orderline
| productid
| Attribute
| Required
| Only 1
| ezprints product SKU
|-
| style="background-color:#ccffcc;" | Orderline
| quantity
| Element
| Required
| Only 1
| Used to specify multiple copies of this product-image combination.
|-
| style="background-color:#ccffcc;" | Orderline
| position
| Element
| Required
| Only 1
| Please specify one of two values: Crop or Fit . Crop means that the image will fill the entire print area with any excess cropped off. Fit means that the entire image will be fit to the printable area of the product, producing a white border where the aspect ratios are different from the product spec.If the position is not specified for an orderline, the default is Fit. Please see the Product Specifications section of this packet for information on each product's Crop or Fit setting.
|-
| style="background-color:#ccffcc;" | Orderline
| productprice
| Element
| Optional
| Only 1
| This optional element allows the partner to specify the retail price for a product. Not visible on the work order.
|-
| style="background-color:#ccffcc;" | Orderline
| productname
| Element
| Optional
| Only 1
| This optional element is used to give the partner the option of naming product items differently from ezprints. If this element is omitted, the default ezprints product description will be used. Custom product descriptions must include print size and paper finish (matte, glossy, lustre, metallic).
|-
| style="background-color:#ccffcc;" | Orderline
| enhance
| Element
| Optional
| Only 1
| Optional tag indicating whether or not an enhancement algorithm should be applied to the image before printing. Can be an empty, self closing element; existance of element indicates the direction to enhance this orderline's image.
|-
| style="background-color:#ccffcc;" | shippingaddress
| <!-- empty -->
| Element
| Required
| Only 1
| 5 children of Shippingaddress are required: address1, city, state (US and Canada only), countrycode, &amp; zip.
|-
| style="background-color:#ccffcc;" | shippingaddress
| companyname
| Element
| Optional
| Only 1
| companyname, if sent, will appear on work order in the Ship To and To areas. 50 character limit.
|-
| style="background-color:#ccffcc;" | shippingaddress
| title
| Element
| Optional
| Only 1
| <!-- empty -->
|-
| style="background-color:#ccffcc;" | shippingaddress
| firstname
| Element
| Optional
| Only 1
| <!-- empty -->
|-
| style="background-color:#ccffcc;" | shippingaddress
| lastname
| Element
| Optional
| Only 1
| <!-- empty -->
|-
| style="background-color:#ccffcc;" | shippingaddress
| address1
| Element
| Required
| Only 1
| Address1 and Address2 print on shipping labels and have a 30 character limit.
|-
| style="background-color:#ccffcc;" | shippingaddress
| address2
| Element
| Optional
| Only 1
| Address1 and Address2 print on shipping labels and have a 30 character limit.
|-
| style="background-color:#ccffcc;" | shippingaddress
| city
| Element
| Required
| Only 1
| <!-- empty -->
|-
| style="background-color:#ccffcc;" | shippingaddress
| state
| Element
| Required
| Only 1
| Valid state and country codes can be found in the Shipping section of the Parnter Web Service Integration Overview packet.
|-
| style="background-color:#ccffcc;" | shippingaddress
| zip
| Element
| Required
| Only 1
| <!-- empty -->
|-
| style="background-color:#ccffcc;" | shippingaddress
| countrycode
| Element
| Required
| Only 1
| Valid state and country codes can be found in the Shipping section of the Parnter Web Service Integration Overview packet.
|-
| style="background-color:#ccffcc;" | shippingaddress
| phone
| Element
| Optional
| Only 1
| 30 character limit.
|-
| style="background-color:#ccffcc;" | shippingaddress
| email
| Element
| Optional
| Only 1
| <!-- empty -->
|}
Meta Keywords:
Meta Description:
Change Comment: