Created : 12 Sept 2017
Last Modified : 20 Mar 2018

***********************************************************************************
Contents:

A. SUMMARY
B. FILE STRUCTURE
C. INSTALLATION INSTRUCTION
D. HOW IT WORKS
E. CONFIGURATION SETTINGS
F. DATABASE TABLES MODIFIED
G. LANGUAGE SETTINGS CHANGED
H. CHANGE LOGS
I. TROUBLESHOOTING
J. FAQ
K. COPYRIGHT NOTICE
L. TERMS AND CONDITIONS
***********************************************************************************

A. SUMMARY
==========
This module is for use with ShipStation Custom Store method.

The Custom Store allows ShipStation to pull VPCart order information, and enables ShipStation to automatically send shipment status and tracking information updates back to your VPCart once a label is created. It’s the best way to sync up orders with ShipStation and have the most seamless experience.

The Custom Store functionality in ShipStation will be similar to popular supported integrations like eBay or Amazon.

To use this module, you must register an account first with ShipStation. More info at: www.shipstation.com

***********************************************************************************

B. FILE STRUCTURE
===================

Files included in the zip are:
- $readme_shipstation800.html
- admin\shipstation_setup.asp
- admin\shipstation_setup_config.asp
- admin\shipstation_setup_process.asp
- admin\vpcart_shipstation_sync.asp
- admin\sqlscripts\shipstation\*

***********************************************************************************

C. INSTALLATION INSTRUCTION
============================

1. Upload below files to your ADMIN folder. If you have renamed your ADMIN folder, then this must be placed in the renamed folder.
- admin\shipstation_setup.asp
- admin\shipstation_setup_config.asp
- admin\shipstation_setup_process.asp
- admin\vpcart_shipstation_sync.asp
- admin\sqlscripts\shipstation\*

2. Log into super admin and execute setup file below eg :
http://www.yourdomain.com/youradminfolder/shipstation_setup.asp

Note:
Replace www.yourdomain.com with your VPCart site url
Replace youradminfolder with your VPCart admin folder name

3. After setup the module, would be redirected Module configuration page for configure the module.

Enable? : Please set to Yes.
Username for Shipstation Custom Store : You need to create a username here to use later for Custom Store.
Password for Shipstation Custom Store : You need to create a password here to use later for Custom Store.
Weight unit used in your VPCart site : Enter Pounds or Ounces or Grams

Click Save button once all filled in.

4. Login to www.shipstation.com using your existing Shipstation account.
NOTE : This is not the username and password you created in step 3 above, but this is your Shipstation Username and Password.



If you don't have account yet, please register one at www.shipstation.com.

5. After logged in, click the Setting icon in the top right.

6. Then in the left panel, click the Selling Channel > Store Setup.



7. Click the green button "Connect a Store or Martketplace".



8. You will see a list of stores. Please scroll down and choose "Custom Store".
Or you can also type in custom store and select it.



9. Now you will connect to your Custom Store. Please enter the following fields :

URL to Custom XML Page : http://www.yourdomain.com/youradminfolder/vpcart_shipstation_sync.asp

Note:
Replace www.yourdomain.com with your VPCart site url
Replace youradminfolder with your VPCart admin folder name

Username : Enter the username you've created in step 3.
Password : Enter the password you've created in step 3.

Map your Custom Store's Order Statuses to ShipStation by placing them in the relevant fields below.
Separate multiple statuses with a comma.

Unpaid Status : please change the value unpaid to : Awaiting Payment
Paid Status : please change the value paid to : Awaiting Shipment
Shipped Status : please change the value shipped to : Shipped
Cancelled Status : please change the value cancelled to : Cancelled
On-Hold Status : please change the value on_hold to : On Hold

Example of screenshot:


Once all fields have been filled, please click Test Connection.

10. If ShipStation able to connect to the page vpcart_shipstation_sync.asp without issue, you should get a message below :



11. Click Connect button.

12. You will see a New Custom Store form. Please enter your Store Name and select your Store Timezone.
You can also configure the other tabs eg Branding, Returns, etc.. if needed which are optional.



13. Click Save Changes button once done.

14. You should see a Completed status that indicate the Custom Store is created successfully and able to sync VPCart orders.



15. At the top menu, click Orders.



16. You should be able to see your recent VPCart orders are there now.
Click the left panel to the Awaiting Shipment menu. All the orders in this section are available for you to assign for shipment and create label.

You will need to click each order number and then select the shipping provider from your Shipstation for each order and create shipping label.



You can also use Service Mapping in ShipStation to map any shipping service from VPCart store with the shipping service provided in ShipStation. You can refer to the following :
https://help.shipstation.com/hc/en-us/articles/206640487-Setting-up-Shipping-Service-Mappings-Video-Tutorial-

You can also watch this video tutorial below on how to get your orders in Shipstation ready to ship :
https://www.shipstation.com/videos/processing-orders/

17. Now login to your VPCart administration.

18. Go to Advanced Settings > Software Configuration.



19. Enter xtracking into the textbox and click Search button.



20. Please set xtracking to Yes and click Continue button.
Activating this feature will allow merchants to see any tracking messages returned by Shipstation for each orders that have been shipped.



21. Go to Advanced Settings > Software Configuration.



22. Enter xendofordervalidpayments into the textbox and click Search button.



23. Please set xendofordervalidpayments value in comma-delimited list for Payment Type (ocardtype) that your site supported.
eg. Credit Card,Paypal,Visa,Mastercard,Discover,Cash,Check



In this module, we utilize the config xendofordervalidpayments as one of criteria in passing the order status for Awaiting Shipment, which is for any VPCart orders with field oprocessed : False and ocardtype contains one of the payment type listed in config xendofordervalidpayments.

If you have any payment gateway installed and show the Payment Type in order administration as that gateway name, then you will also need to include that Payment Type into the list of xendofordervalidpayments config.

For example, for those using Authorize Net DPM gateway to take payment, usually the order made using the payment will show Payment Type as AuthNetDPM. You will then need to include this into the list of xendofordervalidpayments config eg :
Credit Card,Paypal,Visa,Mastercard,Discover,Cash,Check,AuthNetDPM

***********************************************************************************

D. HOW IT WORKS
===============

This Custom Store integration will do two major tasks:

- Automatically import recent VPCart orders data on Shipstation system.
- Automatically update VPCart orders and tracking data with order status, order shipping information and tracking number once order is shipped.

Using this "Custom Store Integration" method, we use a page vpcart_shipstation_sync.asp that is installed in VPCart admin folder for syncing orders.
You register this page URL on the Shipstation account as mentioned on step 9 above so that Shipstation able to recognize which page to sync.

For security reason, ShipStation requires merchant to create their own username and password on VPCart site which has been provided on step 3 above.
This username and password then can be entered into your Custom Store as provided on step 9 above.
If the username and password you created on step 3 is different to what you entered in your Custom Store on step 9, then Shipstation will not able to retrieve any orders.

D1. Retrieving VPCart Orders into Shipstation

When importing VPCart orders into their system, Shipstation send a request GET "export". On this stage, VPCart site will act as "server" and ShipStation will act as "client" that needs the XML order information passed into their system.

We use the following criteria for mapping VPCart orders status with Shipstation order status:

Awaiting Payment : Any VPCart orders with field ocardtype : Pending
Awaiting Shipment : Any VPCart orders with field oprocessed : False and ocardtype contains one of the payment type listed in config xendofordervalidpayments.
Pending Fulfillment : Any VPcart orders with field ocardtype contains error or fail
Shipped : Any VPcart orders with field oprocessed : True and field ostatus : Shipped
Cancelled : Any VPcart orders with field ocardtype : Order Canceled ***
On Hold : Any VPcart orders with field ocardtype : empty

If any orders meet above, we automatically update the <OrderStatus> in xml for order import process in Shipstation Custom Store to that Shipstation Order status.

For any orders that are gift products, VPcart sends <Gift> xml status as True so Shipstation can know the order is a gift, and VPCart also can send the <GiftMessage> xml status which value is retrieved from VPCart gifts table field giftmessage.

For any orders that contains product features, VPCart also can send the product features information to Shipstation during the syncing orders.

When you have setup Custom Store as mentioned in the INSTALLATION INSTRUCTION section, Shipstation then able to sync VPCart orders every few mins automatically. Or you can also manually click the button shown below to get orders from VPCart site.



Once synced, those VPCart orders then able to be viewed on Orders menu at Shipstation.

Those orders in Awaiting Shipment means they are ready for you to assign shipping provider for each order and you can later create shipping label for each order.

D2. Post Shipment Information When Orders Ship

By default, ShipStation posts shipment notifications ('POST') to your VPCart Endpoint using the same page vpcart_shipstation_sync.asp whenever a shipping label is created in ShipStation.

For this process, ShipStation will send a POST action "shipnotify" when sending this notification.

VPCart then able to read this request as a post from Shipstation and will do the following :

a. Update the orders table field ostatus with value 'Shipped' and field oprocessed with value 'True' for the order that Shipstation passed in.
And each shipped order will be automatically "Marked as Processed" in your VPCart Orders administration.

b. Create tracking order record into ordertracking table for that order with details of the shipping tracking details eg :
orderid : xx
trackdate : date when tracking response received from shipstation
trackname : Updated from Shipstation
trackemail : [email protected]
trackcomment : [Provider] - [Service name][Tracking number] eg. UPS - UPS Ground 84200912

Example of VPCart order that has been auto updated with tracking information :



And here is the example of tracking order details for above sample order :



c. Pass response status 200 to Shipstation.
VPcart will send response HTTP status code 200 to indicate that the tracking information was received successfully.

***********************************************************************************

E. CONFIGURATION SETTINGS
=================
New configs :
xshipstation
xshipstation_username
xshipstation_password
xshipstation_weight_unit

F. DATABASE TABLES MODIFIED
===========================

NONE

NONE

2017.10.25 - include oaddress2 paramater to be passed to shipstation
2017.10.28 - fixed issue with shipstation sending tracking back to vpcart returning error due to db type

***********************************************************************************

I. TROUBLESHOOTING
============================

Please submit a ticket to our helpdesk at https://helpdesk.vpcart.com and our support team will assist you.

***********************************************************************************

J. FAQ
============================

1. Does ShipStation provide real-time shipping quotes that can be used at VPCart site checkout?
No. Merchants need a real-time shipping quote extension such as UPS, USPS, FedEx, Australia Post, etc. or have an alternate way to show shipping quotes (e.g., Flat rate charge).

2. How to Process Orders in ShipStation?
You can watch this video tutorial below on how to get your orders in Shipstation ready to ship :
https://www.shipstation.com/videos/processing-orders/

***********************************************************************************
K. COPYRIGHT NOTICE
============================

Copyright (c) 1999-2018 Rocksalt International Pty. Ltd.
All rights reserved.

This software and documentation constitute a published work and
contains valuable trade secrets and proprietary information
belonging to Rocksalt International Pty. Ltd. .
None of the foregoing material may be copied,
duplicated or disclosed without the express written permission
of Rocksalt International Pty. Ltd. .

LICENSEE ACCEPTS VP-ASP Shopping Cart "AS IS" "WITH ALL FAULTS",
Rocksalt International Pty. Ltd. accepts no responsibility for the
operation or performance of the VP-ASP Shopping Cart.
The entire risk of use and consequences of use of the
VP-ASP Shopping Cart falls completely on the Licensee
and Rocksalt International Pty. Ltd. shall not be liable in any respect
for any claims, loss or injury alleged to have resulted
from use of or in reliance on VP-ASP Shopping Cart.

Licensee acknowledges that it has read the foregoing
disclaimers of warranty and limitation of liability
and understands that Licensee assumes
the entire risk of using VP-ASP Shopping Cart.


***********************************************************************************

L. TERMS AND CONDITIONS
============================
ROCKSALT INTERNATIONAL GRANTS TO THE LICENSEE A NON-EXCLUSIVE,
NON-SUB LICENSABLE, NONTRANSFERABLE LICENSE
TO INSTALL AND USE THIS APPLICATION ON A SINGLE DOMAIN FOR
A SINGLE SHOP.

THE CODE IN THE APPLICATION MAY BE MODIFIED FOR USE IN
SETTING UP A SINGLE SHOPPING SITE ON THE WORLD WIDE WEB.

LICENSEE MAY MAKE A COPY OF THE APPLICATION FOR
BACK-UP AND ARCHIVAL PURPOSES, PROVIDED THAT ANY COPY
MUST CONTAIN ALL PROPRIETARY NOTICES INCLUDED
WITH THE APPLICATION.

LICENSEE IS PROHIBITED FROM SELLING OR DISTRIBUTING
THE APPLICATION IN ANY MANNER.

LIMITATION OF LIABILITY.

ROCKSALT INTERNATIONAL AND ITS LICENSORS SHALL
NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE OR ANY
THIRD PARTY AS A RESULT OF USING OR DISTRIBUTING THIS
APPLICATION.

IN NO EVENT WILL ROCKSALT INTERNATIONAL OR ITS LICENSORS
BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA,
OR FOR DIRECT, INDIRECT, SPECIAL,
CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES,
HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LI
ARISING OUT OF THE USE OF OR INABILITY TO USE THE SOFTWARE,
EVEN IF ROCKSALT INTERNATIONAL HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.