Custom Store Reference Guide
Tip
New Version Coming Soon
This version of the Custom Store spec is still fully supported but a new version is coming soon. Both versions will be supported for some time.
The section includes Order Information and ShipNotify field definitions, and the XML Schema for validating order information.
Order Information Field Definitions
* Indicates required fields
| Name | XPath | Max Allowed | Type | Length | Description |
|---|---|---|---|---|---|
| Orders * | Orders | 1 | Container | n/a | Root node |
| Order * | Orders/Order | Unlimited | Container | n/a | Container node for an individual order |
| OrderID * | Orders/Order/OrderID | 1 per Order | String | n/a | Unique identifier for an order. Not displayed to anyone. |
| OrderNumber * | Orders/Order/OrderNumber | 1 per Order | String | 1..50 | User-visible order number. This value can be the same as the OrderID. |
| OrderDate * | Orders/Order/OrderDate | 1 per Order | Date/time | 16 | The date the order was placed. UTC time. Format: MM/dd/yyyy HH:mm. Both 12 and 24 hour notation are allowed. |
| OrderStatus * | Orders/Order/OrderStatus | 1 per Order | String | 1---50 | The status of the order in your system. You will be able to map this status to a ShipStation status when connecting your Web Endpoint as a Selling Channel within ShipStation. |
| LastModified * | Orders/Order/LastModified | 1 per Order | Date/time | 16 | The last time the order was modified in your system. UTC time. Format: MM/dd/yyyy HH:mm |
| ShippingMethod | Orders/Order/ShippingMethod | 1 per Order | String | 0...1000 | Recommended if you know the shipping method that will be used to ship the order. ShipStation can map your shipping methods to actual services. |
| PaymentMethod | Orders/Order/PaymentMethod | 1 per Order | String | 0...50 | Order payment method (e.g. PayPal, Check, Money Order) |
| OrderTotal * | Orders/Order/OrderTotal | 1 per Order | Decimal | 9,2 (Precision Scale) | Total amount of the order. (Nine total digits, up to 7 digits before the decimal point, and up to 2 after.) |
| TaxAmount | Orders/Order/TaxAmount | 1 per Order | Decimal | 9,2 | Tax amount, if any. |
| ShippingAmount * | Orders/Order/ShippingAmount | 1 per Order | Decimal | 9,2 | Shipping amount. |
| CustomerNotes | Orders/Order/CustomerNotes | 1 per Order | String | 0...1000 | Notes left by the customer when placing the order. |
| InternalNotes | Orders/Order/InternalNotes | 1 per Order | String | 0...1000 | Private notes that are only viewed by your company. |
| Gift | Orders/Order/Gift | 1 per Order | Bool | "true" if this order is a gift. | |
| GiftMessage | Orders/Order/GiftMessage | 1 per Order | String | 0...1000 | Contains the customer's gift message. |
| CustomField1 | Orders/Order/CustomField1 | 1 per Order | String | 0...100 | Custom field that will show up in ShipStation's Orders grid. Can also be used in the criteria for ShipStation's filters and automation rules. |
| CustomField2 | Orders/Order/CustomField2 | 1 per Order | String | 0...100 | Custom Field 2 |
| CustomField3 | Orders/Order/CustomField3 | 1 per Order | String | 0...100 | Custom Field 3 |
| RequestedWarehouse | Orders/Order/RequestedWarehouse | 1 per Order | String | 0...100 | Ship From Location (must match Name) |
| Source | Orders/Order/Source | 1 per Order | String | 0...50 | Order source (e.g. eBay, US, Amazon, Buy.com) |
| Customer * | Orders/Order/Customer | 1 per Order | Container | n/a | Container node for the customer's information. |
| CustomerCode * | Orders/Order/Customer/CustomerCode | 1 per Order | String | 1..50 | A unique identifier of the customer in your system. This is often a username or email address. |
| BillTo * | Orders?Order/Customer/BillTo | 1 per Order | Container | n/a | Container node for the customer's billing information. |
| Name * | Orders/Order/Customer/BillTo/Name | 1 per Order | String | 1...100 | The billing name. |
| Company | Orders/Order/Customer/BillTo/Company | 1 per Order | String | 1...100 | The billing company. |
| Phone | Orders/Order/Customer/BillTo/Phone | 1 per Order | String | 0...50 | The billing phone. |
| Orders/Order/Customer/BillTo/Email | 1 per Order | String | 0...100 | Recommended so that ShipStation can notify the buyer when an order ships. | |
| ShipTo * | Orders/Order/Customer/ShipTo | 1 per Order | Container | n/a | Container node for the customer's shipping information. |
| Name * | Orders/Order/Customer/ShipTo/Name | 1 per Order | String | 1...100 | Recipient's name. |
| Company | Orders/Order/Customer/ShipTo/Company | 1 per Order | String | 1...100 | Recipient's company. |
| Address1 * | Orders/Order/Customer/ShipTo/Address1 | 1 per Order | String | 1...200 | Recipient's address line 1. |
| Address2 | Orders/Order/Customer/ShipTo/Address2 | 1 per Order | String | 1...200 | Recipient's address line 2. |
| City * | Orders/Order/Customer/ShipTo/City | 1 per Order | String | 1...100 | Recipient's city. |
| State * | Orders/Order/Customer/ShipTo/State | 1 per Order | String | 2...100 | US and Canadian addresses require the 2 character state/territory code. |
| PostalCode * | Orders/Order/Customer/ShipTo/PostalCode | 1 per Order | String | 0...50 | Required for domestic addresses and many international addresses. |
| Country * | Orders/Order/Customer/ShipTo/Country | 1 per Order | String | 2 | 2-character ISO 3116-1 country code. |
| Phone | Orders/Order/Customer/ShipTo/Phone | 1 per Order | String | 0...50 | Required in some cases (e.g. overnight or international shipping). No specific format. |
| Items * | Orders/Order/Items | 1 per Order | Container | Container node for the order's items. | |
| Item | Orders/Order/Items/Item | Unlimited | String | Container node for an individual order line item. | |
| LineItemID | Orders/Order/Items/Item/LineItemID | 1 per Item | String | 1...50 | Unique identifier for the line item. |
| SKU * | Orders/Order/Items/Item/SKU | 1 per Item | String | 1...50 | Unique identifier for the product that was ordered. |
| Name * | Orders/Order/Items/Item/Name | 1 per Item | String | 1...200 | Name of the product. |
| ImageUrl | Orders/Order/Items/Item/ImageUrl | 1 per Item | String | 0...500 | URL for the product's image. |
| Weight | Orders/Order/Items/Item/Weight | 1 per Item | Decimal | 9,2 | Weight of a single line item. |
| WeightUnits | Orders/Order/Items/Item/WeightUnits | 1 per Item | Enum | Value should be one of the following: Pounds, Ounces, Grams | |
| Quantity * | Orders/Order/Items/Item/Quantity | 1 per Item | Integer | 1...99999 | Quantity of items ordered. |
| UnitPrice * | Orders/Order/Items/Item/UnitPrice | 1 per Item | Decimal | 9,2 | Price of a single item. |
| Location | Orders/Order/Items/Item/Location | 1 per Item | String | 0...100 | Location of the product in the Warehouse |
| Adjustment | Orders/Order/Items/Item/Adjustment | 1 per Item | Bool | "true" if the line item represents a coupon, discount, or other adjustment. Note that any line item that is an adjustment must have a negative "UnitPrice" value. | |
| Options | Orders/Order/Items/Item/Options | 1 per Item | Container | Container note for item options (e.g. color, size, etc.) | |
| Option | Orders/Order/Items/Item/Options/Option | 10 per Item | Container | Container node for an individual option value. | |
| Name * | Orders/Order/Items/Item/Options/Option/Name | 1 per Option | String | 1...100 | The name of the option (e.g. Size). |
| Value * | Orders/Order/Items/Item/Options/Option/Value | 1 per Option | String | 1...100 | The value of the option (e.g. XL). |
| Weight | Orders/Order/Items/Item/Options/Option/Weight | 1 per Option | Decimal | 9 (with 2 decimal precision) | If the option adds to the item weight, you may specify the additional weight here. This should be in the same units specified in WeightUnits. It should be the additional weight for a single quantity. |
XML Schema for Validating Order Information
The Order XML will be validated against the following schema:
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="Orders">
<xs:complexType>
<xs:sequence>
<xs:element name="Order" maxOccurs="unbounded" minOccurs="0">
<xs:complexType>
<xs:all>
<xs:element type="String50" name="OrderID" minOccurs="0"/>
<xs:element type="String50" name="OrderNumber"/>
<xs:element type="DateTime" name="OrderDate"/>
<xs:element type="String50" name="OrderStatus"/>
<xs:element type="DateTime" name="LastModified"/>
<xs:element type="String100" name="ShippingMethod" minOccurs="0"/>
<xs:element type="String50" name="PaymentMethod" minOccurs="0"/>
<xs:element type="xs:decimal" name="OrderTotal"/>
<xs:element type="xs:decimal" name="TaxAmount" minOccurs="0"/>
<xs:element type="xs:decimal" name="ShippingAmount" minOccurs="0"/>
<xs:element type="String1000" name="CustomerNotes" minOccurs="0"/>
<xs:element type="String1000" name="InternalNotes" minOccurs="0"/>
<xs:element type="xs:boolean" name="Gift" minOccurs="0"/>
<xs:element type="String1000" name="GiftMessage" minOccurs="0"/>
<xs:element type="String100" name="CustomField1" minOccurs="0"/>
<xs:element type="String100" name="CustomField2" minOccurs="0"/>
<xs:element type="String100" name="CustomField3" minOccurs="0"/>
<xs:element type="String100" name="RequestedWarehouse" minOccurs="0"/>
<xs:element type="String50" name="Source" minOccurs="0" />
<xs:element name="Customer">
<xs:complexType>
<xs:all>
<xs:element type="String100" name="CustomerCode"/>
<xs:element name="BillTo">
<xs:complexType>
<xs:all>
<xs:element type="String100" name="Name"/>
<xs:element type="String100" name="Company" minOccurs="0"/>
<xs:element type="String50" name="Phone" minOccurs="0"/>
<xs:element type="Email" name="Email" minOccurs="0"/>
<xs:element type="String200" name="Address1" minOccurs="0"/>
<xs:element type="String200" name="Address2" minOccurs="0"/>
<xs:element type="String100" name="City" minOccurs="0"/>
<xs:element type="String100" name="State" minOccurs="0"/>
<xs:element type="String50" name="PostalCode" minOccurs="0"/>
<xs:element type="StringExactly2" name="Country" minOccurs="0"/>
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="ShipTo">
<xs:complexType>
<xs:all>
<xs:element type="String100" name="Name"/>
<xs:element type="String100" name="Company" minOccurs="0"/>
<xs:element type="String200" name="Address1"/>
<xs:element type="String200" name="Address2" minOccurs="0"/>
<xs:element type="String100" name="City"/>
<xs:element type="String100" name="State" minOccurs="0"/>
<xs:element type="String50" name="PostalCode" minOccurs="1"/>
<xs:element type="StringExactly2" name="Country"/>
<xs:element type="String50" name="Phone" minOccurs="0"/>
</xs:all>
</xs:complexType>
</xs:element>
</xs:all>
</xs:complexType>
</xs:element>
<xs:element name="Items">
<xs:complexType>
<xs:sequence>
<xs:element name="Item" maxOccurs="unbounded" minOccurs="0">
<xs:complexType>
<xs:all>
<xs:element type="String50" name="LineItemID" minOccurs="0"/>
<xs:element type="String100" name="SKU"/>
<xs:element type="String200" name="Name"/>
<xs:element type="xs:boolean" name="Adjustment" minOccurs="0"/>
<xs:element type="xs:anyURI" name="ImageUrl" minOccurs="0"/>
<xs:element type="xs:decimal" name="Weight" minOccurs="0"/>
<xs:element name="WeightUnits" minOccurs="0">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:patternvalue="pound|pounds|lb|lbs|gram|grams|gm|oz|ounces|Pound|Pounds|Lb|Lbs|Gram|Grams|Gm|Oz|Ounces|POUND|POUNDS|LB|LBS|GRAM|GRAMS|GM|OZ|OUNCES"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element type="xs:int" name="Quantity"/>
<xs:element type="xs:decimal" name="UnitPrice"/>
<xs:element type="String100" name="Location" minOccurs="0"/>
<xs:element name="Options" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element name="Option" maxOccurs="100" minOccurs="0">
<xs:complexType>
<xs:all>
<xs:element type="String100" name="Name"/>
<xs:element type="String100" name="Value"/>
<xs:element type="xs:decimal" name="Weight" minOccurs="0"/>
</xs:all>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:all>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:all>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute type="xs:short" name="pages"/>
</xs:complexType>
</xs:element>
<xs:simpleType name="DateTime">
<xs:restriction base="xs:string">
<xs:pattern value="[0-9][0-9]?/[0-9][0-9]?/[0-9][0-9][0-9]?[0-9]? [0-9][0-9]?:[0-9][0-9]?:?[0-9]?[0-9]?. ?[aApP]?[mM]?"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="Email">
<xs:restriction base="xs:string">
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="StringExactly2">
<xs:restriction base="xs:string">
<xs:minLength value="2"/>
<xs:maxLength value="2"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="String30">
<xs:restriction base="xs:string">
<xs:maxLength value="30"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="String50">
<xs:restriction base="xs:string">
<xs:maxLength value="50"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="String100">
<xs:restriction base="xs:string">
<xs:maxLength value="100"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="String200">
<xs:restriction base="xs:string">
<xs:maxLength value="200"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="String1000">
<xs:restriction base="xs:string">
<xs:maxLength value="1000"/>
</xs:restriction>
</xs:simpleType>
</xs:schema>