Warehouse and Shipping XML Order Submitter FAQ

XML Order Submitter FAQ

Where do I start?

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.
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.
If you need support please send an e-mail to support+dev “at” shipwire.com and we’ll get to it quickly.
Use the XML Test Harness to submit a test order directly to us. Note that it is submitting orders to:

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

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

https://api.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.
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://api.shipwire.com/exec/FulfillmentServices.test.php

If possible, use the XML Code Samples to build your own script.
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:

Sign up for a test account.
Post to your test account, 1 order, with 1 item. Confirm an XML reply of 1 order, with 1 item.
Post 1 order, with 3 items. Confirm a reply of 1 order, with 3 items.
Post 3 orders, with 1 item each. Confirm a reply of 3 orders, with a total of 3 items.
Post 3 orders, with 3 item each. Confirm a reply of 3 orders, with a total of 9 items.
Sign into your test account, and view each of the 8 orders posted above. Doublecheck that all fields look correct.
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:

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.

What do I pass in the “Warehouse” Field?

You don’t need to identify a specific warehouse for the order in the XML you send to Shipwire. We provide this field for a very limited set of customer needs and 99.9% of customers don’t need this field as Shipwire will route the order to the warehouse that is holding inventory closest to the buyer. It is best to pass “00″ in that field: “<Warehouse>00</Warehouse>”

How should my address Country and State/Province information be provided?

For best results the Country address information must be provided using the proper two letter ISO Country Code. In addition when possible the proper State or Province abbriviation should be used as well.

What do I pass in the <AffiliateId> field?

The <AffiliateID> field is an optional field. If you are an end merchant coding to our API’s you can probably just ignore this. If you are a Shipwire Partner building an application connection to Shipwire and you have signed up as a Shipwire Partner then we urge you to pass along your partner ID in the AffiliateID field (Also has been used in the <referrer> field; however for new builds we preferrer AffiliateID). This will help us track orders to your integration. This is the 4 numbers at the end of your Partner URL. Example of a partner ID is 1234 when the URL ends with “o.php?id=1234″. It is optional to put the 1234 in the AffiliateID field; but, it is helpful for tracking lead origin especially for modules that are installed scripts (example is open source modules).

What is AffiliateStatus?

Again, this is for our partners and merchants coding to Shipwire can ignore. <AffiliateStatus> is for partners that want to build in auditing of the Shipwire orders for their integrations. This field represents the status of the order, for affiliate credit eligibility. Only orders marked “shipwireFulfilled” are eligible for affiliate credit. Orders that return an AffiliateStatus of “canceled”, “held”, “duplicate” or “merchantFulfilled” are not commissionable orders pursuant to our shipping affiliate terms.

How do I get Developer Support?

Application developers that are integrating to Shipwire can send us an e-mail at support+dev (at) shipwire (dot) com. We will try and get your question answered quickly.

Connect with us