Where do I start?

First sign up for a free Shipwire account. You will need a Shipwire email and password, for authentication. You can also then see test orders appear in your account just as your customers will. In your account, just press the My Account tab, and then press the History sub-tab, to monitor new test orders. You can then confirm all fields are successfully passed into our database. Signing up for an account has no cost or obligation associated with it.

Second walk through the Example XML Order. The example contains three orders (ids test-485, test-486, and test-487). A Shipwire email address and password will be in <EmailAddress> and <Password> tags. The type of server will be in a <Server> tag, and set to Test or Production. Each order lists the shipping information in the <AddressInfo> tag with the ‘type’ parameter set to “ship”. Each item in the order will be listed in an <Item> tag with a parameter “num” set to the line number of the item. All other information, such as Warehouse and Shipping, is optional, since this information can be preset inside a Shipwire account. Please read the XML Schema Library for more information. on which fields are optional, which are required, what is expected in each field, and why.

Third use Shipwire Priority Support if you have any questions or problems.

Fourth use the XML Test Harness to submit a test order directly to us. Note that it is submitting orders to:

https://www.shipwire.com/exec/FulfillmentServices.php

Further note that it is posting the XML, to the OrderListXML variable, in a URL encoded form:

https://www.shipwire.com/exec/FulfillmentServices.php?OrderListXML=
%3COrderList%3E%0A+++%3CEmailAddress%3Eyouremail.com…

If you insert your Shipwire email and password, you will see that the you are now authenticated, and able to further test the XML.

Fifth if you only want to see the XML being received by Shipwire, use the Echo Only form. This is useful if your script appears to be producing perfect XML, but you are not getting any response from Shipwire. The most likely culprits are that you’re not posting to the OrderListXML variable, or you’re not posting with proper URL encoded syntax. Note that it is submitting orders to:

https://www.shipwire.com/exec/FulfillmentServices.test.php

View proper URL encoding?

Sixth, if possible, use the XML Code Samples to build your own script.

Seventh, use the XML Schema Library to check field requirements and limitations. Of note: StoreAccountName is primarily for Yahoo! Stores, where authentication is not possible. Referrer is primarily for Order Management Software, so that our partners can identify all orders from their customers in the Shipwire system. If you are a partner, simply select a unique ALL CAPS identifier, such as YAHOOSTORES or YHOO109. Server should either be “Test” or “Production”. When orders are submitted to an account that has zero funds, it’s assumed all orders are Test. The Warehouse field is for future use. Currently setting it to “00″ will leave it to Shipwire to choose the best warehouse for shipping an order from. In the future, your software will be able to designate specific warehouses to receive specific orders.

How can I confirm orders are being received correctly?

Error checking will check for valid fields. However there are four different ways we can receive orders, and if the XML is formatted incorrectly, items in a multi-item order can get lost. The following test will validate all four types of orders:

1. Sign up for a test account.
2. Post to your test account, 1 order, with 1 item. Confirm an XML reply of 1 order, with 1 item.
3. Post 1 order, with 3 items. Confirm a reply of 1 order, with 3 items.
4. Post 3 orders, with 1 item each. Confirm a reply of 3 orders, with a total of 3 items.
5. Post 3 orders, with 3 item each. Confirm a reply of 3 orders, with a total of 9 items.
6. Sign into your test account, and view each of the 8 orders posted above. Doublecheck that all fields look correct.
7. Contact Priority Support and ask us to doublecheck each of the 8 orders posted above as well. All we need is your Shipwire email address.

What should I be extra careful about?

Read the next question carefully. Everything may seem fine in your testing, but the following question may come up in a real-world scenario.

What do I do if I’m unable to post items correctly?
There are two reported reasons for items to post incorrectly.

The first reason, as described in OrderList.dtd, is misuse of the apostrophe in the Description field. Be sure apostrophes such as in “A Bug’s Life” are not URL encoded, e.g. “A Bug’s Life”.

The second reason is an incorrect item ID. As described in OrderList.dtd, the first item must have an ID of “0″, followed by 1, 2, 3, … For an example, please review the example XML order.

APO orders (orders to a military base are also worth extra consideration. Make sure your customers’ APO addresses meet one of the following criteria:

• There is an official APO code in the state field: either AA (Americas), AE (Europe), or AP (Pacific) depending on where the consignee is stationed.
• Or, the shipment is addressed to city “APO” or “FPO” in California (AP), Florida (AA), or New York (AE). This is the traditional way to “force” an APO/FPO shipment for a shopping cart/system that does not support the APO states.

What does the XML Response look like?

Here is a sample response. 3 orders were submitted:

<SubmitOrderResponse>
<Status>0</Status>
<TotalOrders>3</TotalOrders>
<TotalItems>3</TotalItems>
<TransactionId>1172083834-808385-1</TransactionId>
</SubmitOrderResponse>

Note that no Shipwire ID is returned via the API. Only a “TransactionId” for the entire order batch. There is one “TransactionId” for the batch. This is intended to confirm the batch was received. It does not correspond with any specific order. A future version of the interface will provide a Shipwire ID for each individual order.

Will there be future upgrades? Will they be backward compatible?

As we continually add new features, we will do our best to add new attributes and tags to support additional information. Since we will not subtract from, or rearrange the existing attributes/parameters, your existing XML parsing software shouldn’t be affected by the new information.