X-Cart:ShippingEasy - Revision history

Dohtur: /* Integrating your X-Cart store with ShippingEasy */

2014-12-10T09:30:13Z

‎Integrating your X-Cart store with ShippingEasy

Dohtur: /* Order status mapping */

2014-11-11T13:38:06Z

‎Order status mapping

Dohtur: /* Integrating your X-Cart store with ShippingEasy */

2014-11-11T10:41:58Z

‎Integrating your X-Cart store with ShippingEasy

Dohtur at 00:40, 6 November 2014

2014-11-06T00:40:16Z

Dohtur: Created page with '==Overview== X-Cart's ShippingEasy module provides integration with [http://shippingeasy.com/ ShippingEasy], a cloud-based shipping solution that allows you to automate shipping …'

2014-11-06T00:34:17Z

Created page with '==Overview== X-Cart's ShippingEasy module provides integration with [http://shippingeasy.com/ ShippingEasy], a cloud-based shipping solution that allows you to automate shipping …'

New page

==Overview==
X-Cart's ShippingEasy module provides integration with [http://shippingeasy.com/ ShippingEasy], a cloud-based shipping solution that allows you to automate shipping and lower shipping costs.
 

==ShippingEasy module system requirements and installation==
See [[X-Cart:ShippingEasy module installation|ShippingEasy module installation]].
 

==Integrating your X-Cart store with ShippingEasy==
To integrate your X-Cart store with ShippingEasy:
# Sign up for an account with [http://shippingeasy.com/ ShippingEasy]. For detailed information, see the [https://support.shippingeasy.com/entries/23453187-How-to-Create-a-ShippingEasy-account How to create a ShippingEasy account] guide on the ShippingEasy website.
# If you haven't yet done so, [[X-Cart:ShippingEasy module installation|install]] the ShippingEasy module in your X-Cart store.
# To complete the integration of your X-Cart store with ShippingEasy, you will need access to both your X-Cart store's Admin area and your ShippingEasy account settings. So sign in to both the sites and keep them open in your web browser tabs. For a production ShippingEasy account, to access your account settings, use the URL https://app.shippingeasy.com/settings, for a staging account - https://staging.shippingeasy.com/settings.
# (''Skip this step if you have already configured your X-Cart store's settings in ShippingEasy during registration''): Add your X-Cart store to the list of stores in your ShippingEasy account: 
## In the '''Settings''' section of your ShippingEasy account, click on the '''Stores''' link under '''Integrations''': [[File:shippingeasy_stores.png|border]] 
## Click the '''+ Add New''' button on the right-hand side of the screen: [[File:shippingeasy_add_new_store.png|border]] This opens a screen where you will be able to provide the details of your X-Cart store: [[File:shippingeasy_platform.png|border]] 
## From the '''Platform''' drop-down box, select ''X-Cart''. In the '''Store URL''' field below, enter your X-Cart store's URL.
## Click '''Save'''.
## Enter the required store settings and click '''Save''' at the bottom of the page. This creates an entry for your X-Cart store in your list of stores in ShippingEasy: [[File:shippingeasy_store_details.png|border]]
# In your X-Cart store's Admin area, go to the '''Modules''' section ('''Settings''' menu -> '''Modules'''), locate the entry for 'ShippingEasy' and click the Configure link next to it. [[File:shippingeasy_configure.png|border]] You should now see the ShippingEasy module configuration page: [[File:shippingeasy_config_settings1.png|border]] The page provides three fields that you will need to fill with values copied from your ShippingEasy account settings: your '''API Key''', '''API Secret''' and '''Store API Key'''.
# Back in the browser tab where you are using ShippingEasy, copy the Store API Key for your X-Cart store: [[File:shippingeasy_store_api_key.png |border]] Paste this value into the '''Store API Key''' field on the ShippingEasy module configuration page in your X-Cart store.
# In ShippingEasy, click on the '''Settings''' tab, then click on the '''API Credentials''' link under '''Account Settings''': [[File:shippingeasy_api_credentials.png|border]] Your API Key and API Secret will be displayed: [[File:shippingeasy_api_credentials1.png|border]] Copy and paste these values one by one into the '''API Key''' and '''API Secret''' fields on the ShippingEasy module configuration page in your X-Cart store.
# If you are a third party developer using a staging ShippingEasy account, select the '''Staging account''' option on the ShippingEasy module configuration page in X-Cart. For production use, leave the '''Staging account''' check box unselected.
# Click the '''Apply changes''' button at the bottom of the ShippingEasy module configuration page in X-Cart to save the module configuration.
# Make the Shipment Callback URL that was automatically formed for your store by ShippingEasy as "Store URL + /shipment/callback" actually work for your store. To do so, insert the following rewrite rule into the .htaccess file located in your X-Cart installation directory:
<pre>
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteRule ^shipment/callback shippingeasy_callback.php
</IfModule>
</pre>
::{{Note1|'''Important''': If your store uses the [[X-Cart:Clean_URLs | Clean URLs]] feature, make sure this code block goes ''before'' the code block for clean URLs in your .htaccess file.}}
That is all. You have completed integrating your X-Cart store with ShippingEasy. The next step will be to [[X-Cart:ShippingEasy#Activating and deactivating the module|activate the ShippingEasy module]] and [[X-Cart:ShippingEasy#Order status mapping|map your X-Cart order statuses to order statuses in ShippingEasy]], after which the module will be fully ready to use.
 

==Activating and deactivating the module==
If the module ShippingEasy is installed, but not active, you can enable (activate) it.

'''To enable the module''':

# Go to the '''Modules''' section of your store's Admin area ('''Settings''' menu -> '''Modules'''). This opens the list of your store's installed modules.
# Locate the entry for the ShippingEasy module and select the Enable check box on the left. [[File:shippingeasy_enable.png|border]]
# Depending on the version of X-Cart you are using, you may need to apply the change by clicking '''Apply changes'''. The module will be enabled. [[File:shippingeasy_installed_enabled.png|border]]

It is possible to temporarily disable (deactivate) the installed ShippingEasy module. Deactivation stops the module from operation, but it does not remove any settings you made to the module configuration nor clear any data that was generated during the period that the module was in operation. If you wish to completely remove all the data related to using the module, you need to uninstall it. See [[X-Cart:ShippingEasy_module_installation#Uninstallation|ShippingEasy module: Uninstallation]] for more info.

'''To disable the module''':

# Go to the '''Modules''' section of your store's Admin area ('''Settings''' menu -> '''Modules''').
# Locate the entry for the ShippingEasy module and unselect the Enable check box on the left.[[File:shippingeasy_disable.png|border]]
# Depending on the version of X-Cart you are using, you may need to apply the change by clicking '''Apply changes'''. The module will be disabled. [[File:shippingeasy_installed.png|border]]
 

==Order status mapping==
Order statuses used by ShippingEasy are not the same as those used by X-Cart, so, before orders from your X-Cart store can be exported to ShippingEasy, you will need to map order statuses in X-Cart to order statuses in ShippingEasy. To complete the task you will need to specify all the X-Cart statuses with which orders will need to be sent to ShippingEasy and - for each of these statuses - to specify the respective matching ShippingEasy statuses.

Here's how you can do it:
# In your X-Cart store's Admin area, go to the '''ShippingEasy statuses''' page ('''Settings''' menu -> '''ShippingEasy statuses'''): [[File:shippingeasy_statuses.png|border]] 
# In the '''Add new''' section of the page, adjust the drop-down boxes in the '''X-Cart status''' and '''ShippingEasy status''' columns so that they show a pair of matching statuses in X-Cart and in ShippingEasy. For example, if you want order info to be sent to ShippingEasy when an order gets the status "Processed" in X-Cart, and you want this order to be marked as "Awaiting shipment" in ShippingEasy, you should select "Processed" from the drop-down box in the '''X-Cart status''' column and "Awaiting payment" from the drop-down box in the '''ShippingEasy status''' column: [[File:shippingeasy_add_status.png|border]] 
# Click '''Add'''. The matching statuses will be added to the table above: [[File:shippingeasy_add_status1.png|border]] 
# Repeat steps 1-3 if you need to specify more matching pairs of statuses. As a result, you should have all the X-Cart statuses for which order info needs to be sent automatically to ShippingEasy listed in the '''X-Cart status''' column, and their respective matching ShippingEasy statuses listed on the opposite side in the '''ShippingEasy status''' column:[[File:shippingeasy_add_status2.png|border]] 
Note that your store will send order information to ShippingEasy no more than once per order. This means that when an order in X-Cart receives any of the statuses for which you have specified a matching status in ShippingEasy, information about this order will be automatically exported to ShippingEasy; if afterwards the status of this order in X-Cart changes to another status listed in the table, its information will ''not'' be sent to ShippingEasy again. For example, according to the order statuses configuration demonstrated in the snapshot above (Processed->Awaiting shipment, Queued -> Awaiting payment), an order that gets the status "Queued" in X-Cart will be sent to ShippingEasy; when this order is marked as "Processed", it won't be sent to ShippingEasy a second time.
 

==Manual export of orders to ShippingEasy==
In addition to automated export of orders to ShippingEasy based on orders receiving ShippingEasy exportable statuses, X-Cart's ShippingEasy module also supports export of orders to ShippingEasy in manual mode. This feature can be useful if you want to export to ShippingEasy some orders that had received ShippingEasy exportable statuses before these statuses were defined as such in the "ShippingEasy statuses" mapping table.

To export an order to ShippingEasy manually, use one of the following methods:
* Method 1 (can be used to bulk export multiple orders):
# In the '''Orders''' section of your X-Cart store's Admin area, find the orders you want to export and select the check boxes to the left of their numbers in the Orders list.
# Click the '''Export to ShippingEasy''' button at the bottom of the screen. [[File:export2shippingeasy1.png|border]] The selected orders will be exported to ShippingEasy. A success message will be displayed at the top of the screen: [[File:exported_successfully.png|760px|border]] 
* Method 2:
# In the '''Orders''' section of your X-Cart store's Admin area, find the order you want to export and open its details for viewing.
# On the page providing the order's details (Order details page), click the '''Export to ShippingEasy''' button. [[File:export2shippingeasy.png|border]] The order will be exported to ShippingEasy. A success message will be displayed at the top of the screen: [[File:exported_successfully.png|760px|border]] 

==Canceling orders==
When an order gets canceled in X-Cart (i.e. gets the status "Failed" or "Declined"), the ShippingEasy module sends an order cancellation request to ShippingEasy. As a result, the respective order in ShippingEasy is removed. The process is fully automated, so you do not have to do the cancellation on the ShippingEasy end manually. 

==Viewing shipment information==
When an order is shipped, ShippingEasy sends shipment related information back to your X-Cart store. This includes information about the carrier used, the shipping cost and the tracking number assigned to the shipment. In X-Cart this information is written to the '''Order notes (not visible to customer)''' field of the order details. The tracking number for the order is written to the '''Tracking number''' field of the order details. Here's what it looks like on the Order details page:
::[[File:shippingeasy_shipinfo.png|border]] (For orders shipped using multiple parcels more than one tracking numbers may be received; in this case, all of them will be listed in the '''Tracking number''' field, separated by commas). 

==Updating order statuses for shipped orders==
When an order is shipped in ShippingEasy, ShippingEasy notifies your X-Cart store about it, and the status of the order in your X-Cart store is automatically updated to either "Completed" or "Partially shipped".

[[Category:X-Cart modules]]

@@ Line 62: / Line 62: @@
 Here's how you can do it:
 # In your X-Cart store's Admin area, go to the '''ShippingEasy statuses''' page ('''Settings''' menu -> '''ShippingEasy statuses'''):<br />[[File:shippingeasy_statuses.png|border]]<br /><br />
-# In the '''Add new''' section of the page, adjust the drop-down boxes in the '''X-Cart status''' and '''ShippingEasy status''' columns so that they show a pair of matching statuses in X-Cart and in ShippingEasy. For example, if you want order info to be sent to ShippingEasy when an order gets the status "Processed" in X-Cart, and you want this order to be marked as "Awaiting shipment" in ShippingEasy, you should select "Processed" from the drop-down box in the '''X-Cart status''' column and "Awaiting payment" from the drop-down box in the '''ShippingEasy status''' column:<br />[[File:shippingeasy_add_status.png|border]]<br /><br />
+# In the '''Add new''' section of the page, adjust the drop-down boxes in the '''X-Cart status''' and '''ShippingEasy status''' columns so that they show a pair of matching statuses in X-Cart and in ShippingEasy. For example, if you want order info to be sent to ShippingEasy when an order gets the status "Processed" in X-Cart, and you want this order to be marked as "Awaiting shipment" in ShippingEasy, you should select "Processed" from the drop-down box in the '''X-Cart status''' column and "Awaiting shipment" from the drop-down box in the '''ShippingEasy status''' column:<br />[[File:shippingeasy_add_status.png|border]]<br /><br />
 # Click '''Add'''. The matching statuses will be added to the table above:<br />[[File:shippingeasy_add_status1.png|border]]<br /><br />
 # Repeat steps 1-3 if you need to specify more matching pairs of statuses. As a result, you should have all the X-Cart statuses for which order info needs to be sent automatically to ShippingEasy listed in the '''X-Cart status''' column, and their respective matching ShippingEasy statuses listed on the opposite side in the '''ShippingEasy status''' column:[[File:shippingeasy_add_status2.png|border]]<br /><br />

@@ Line 10: / Line 10: @@
 ==Integrating your X-Cart store with ShippingEasy==
-To integrate your X-Cart store with ShippingEasy:
+To integrate your X-Cart store with ShippingEasy, complete the following steps:
-# Sign up for an account with [http://shippingeasy.com/ ShippingEasy]. For detailed information, see the [https://support.shippingeasy.com/entries/23453187-How-to-Create-a-ShippingEasy-account How to create a ShippingEasy account] guide on the ShippingEasy website.
+# If you haven't yet done so, [[X-Cart:ShippingEasy module installation|install]] the ShippingEasy module in your X-Cart store. As a result, you should have the module ShippingEasy listed in your store's Modules section ('''Settings''' menu -> '''Modules''').
-# If you haven't yet done so, [[X-Cart:ShippingEasy module installation|install]] the ShippingEasy module in your X-Cart store.
+# Сlick the Configure link for 'ShippingEasy' to access the module's settings page:<br />[[File:shippingeasy_configure.png|border]]<br /><br />You should now see the ShippingEasy module configuration page:<br />[[File:shippingeasy_config_settings1.png|border]]<br /><br />
-# To complete the integration of your X-Cart store with ShippingEasy, you will need access to both your X-Cart store's Admin area and your ShippingEasy account settings. So sign in to both the sites and keep them open in your web browser tabs. For a production ShippingEasy account, to access your account settings, use the URL https://app.shippingeasy.com/settings, for a staging account - https://staging.shippingeasy.com/settings.
+# At the top of the ShippingEasy module configuration page you should be able to see a link that says "View details and get your API credentials here". If you do not yet have an account with [http://shippingeasy.com/integrate-your-shipping-for-xcart-with-the-shippingeasy-app/?se-ref=96 ShippingEasy], you can follow this link to sign up. For detailed information on creating a ShippingEasy account, see the [https://support.shippingeasy.com/entries/23453187-How-to-Create-a-ShippingEasy-account How to create a ShippingEasy account] guide on the ShippingEasy website.
 # (''Skip this step if you have already configured your X-Cart store's settings in ShippingEasy during registration''): Add your X-Cart store to the list of stores in your ShippingEasy account:<br />
 ## In the '''Settings''' section of your ShippingEasy account, click on the '''Stores''' link under '''Integrations''':<br />[[File:shippingeasy_stores.png|border]]<br /><br />
@@ Line 20: / Line 21: @@
 ## Click '''Save'''.
 ## Enter the required store settings and click '''Save''' at the bottom of the page. This creates an entry for your X-Cart store in your list of stores in ShippingEasy:<br />[[File:shippingeasy_store_details.png|border]]
-# In your X-Cart store's Admin area, go to the '''Modules''' section ('''Settings''' menu -> '''Modules'''), locate the entry for 'ShippingEasy' and click the Configure link next to it.<br />[[File:shippingeasy_configure.png|border]]<br /><br />You should now see the ShippingEasy module configuration page:<br />[[File:shippingeasy_config_settings1.png|border]]<br /><br />The page provides three fields that you will need to fill with values copied from your ShippingEasy account settings: your '''API Key''', '''API Secret''' and '''Store API Key'''.
+# Configure the ShippingEasy module in X-Cart:
-# Back in the browser tab where you are using ShippingEasy, copy the Store API Key for your X-Cart store:<br />[[File:shippingeasy_store_api_key.png |border]]<br /><br />Paste this value into the '''Store API Key''' field on the ShippingEasy module configuration page in your X-Cart store.
+## From the details of your X-Cart store in ShippingEasy ('''Settings''' -> '''Stores'''), copy the Store API Key:<br />[[File:shippingeasy_store_api_key.png |border]]<br /><br />
-# In ShippingEasy, click on the '''Settings''' tab, then click on the '''API Credentials''' link under '''Account Settings''':<br />[[File:shippingeasy_api_credentials.png|border]]<br /><br />Your API Key and API Secret will be displayed:<br />[[File:shippingeasy_api_credentials1.png|border]]<br /><br />Copy and paste these values one by one into the '''API Key''' and '''API Secret''' fields on the ShippingEasy module configuration page in your X-Cart store.
+## Switch back to the browser tab where you are using X-Cart and paste the value you have just copied into the '''Store API Key''' field on the ShippingEasy module configuration page.
-# If you are a third party developer using a staging ShippingEasy account, select the '''Staging account''' option on the ShippingEasy module configuration page in X-Cart. For production use, leave the '''Staging account''' check box unselected.
+## Back in the browser tab with ShippingEasy, click on the '''Settings''' tab, then click on the '''API Credentials''' link under '''Account Settings''':<br />[[File:shippingeasy_api_credentials.png|border]]<br /><br />Your API Key and API Secret will be displayed:<br />[[File:shippingeasy_api_credentials1.png|border]]<br /><br />
-# Click the '''Apply changes''' button at the bottom of the ShippingEasy module configuration page in X-Cart to save the module configuration.
+## Copy and paste these values one by one into the '''API Key''' and '''API Secret''' fields on the ShippingEasy module configuration page in your X-Cart store.
 # Make the Shipment Callback URL that was automatically formed for your store by ShippingEasy as "Store URL + /shipment/callback" actually work for your store. To do so, insert the following rewrite rule into the .htaccess file located in your X-Cart installation directory:
 <pre>

@@ Line 32: / Line 32: @@
 <IfModule mod_rewrite.c>
 RewriteEngine On
-RewriteRule ^shipment/callback shippingeasy_callback.php
+RewriteRule ^shipment/callback shippingeasy_callback.php?shopkey=XXX
 </IfModule>
 </pre>
 ::{{Note1|'''Important''': If your store uses the [[X-Cart:Clean_URLs | Clean URLs]] feature, make sure this code block goes ''before'' the code block for clean URLs in your .htaccess file.}}
 That is all. You have completed integrating your X-Cart store with ShippingEasy. The next step will be to [[X-Cart:ShippingEasy#Activating and deactivating the module|activate the ShippingEasy module]] and [[X-Cart:ShippingEasy#Order status mapping|map your X-Cart order statuses to order statuses in ShippingEasy]], after which the module will be fully ready to use.