Difference between revisions of "Draft:X-Cart:ShippingEasy"

From X-Cart 4 Classic
Jump to: navigation, search
m
m (Redirected page to X-Cart:ShippingEasy)
 
(30 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
#REDIRECT [[X-Cart:ShippingEasy]]
 +
 
==Overview==
 
==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.
 +
<br /><br />
  
 
==ShippingEasy module system requirements and installation==
 
==ShippingEasy module system requirements and installation==
 
See [[X-Cart:ShippingEasy module installation|ShippingEasy module installation]].
 
See [[X-Cart:ShippingEasy module installation|ShippingEasy module installation]].
 +
<br /><br />
  
 
==Integrating your X-Cart store with ShippingEasy==
 
==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.
 
# 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.
 
# If you haven't yet done so, [[X-Cart:ShippingEasy module installation|install]] the ShippingEasy module in your X-Cart store.
# To integrate 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 be sure to sign in to both the sites and keep them open in your web browser tabs. For a production ShippingEasy account, the account settings can be accessed at https://app.shippingeasy.com/settings, for a staging account - at https://staging.shippingeasy.com/settings.
+
# 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:<br />
 
# (''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'''.
+
## In the '''Settings''' section of your ShippingEasy account, click on the '''Stores''' link under '''Integrations''':<br />[[File:shippingeasy_stores.png|border]]<br /><br />
## Click the '''+ Add New''' button on the right-hand side of the screen.
+
## Click the '''+ Add New''' button on the right-hand side of the screen:<br />[[File:shippingeasy_add_new_store.png|border]]<br /><br />This opens a screen where you will be able to provide the details of your X-Cart store:<br />[[File:shippingeasy_platform.png|border]]<br /><br />
 
## From the '''Platform''' drop-down box, select ''X-Cart''. In the '''Store URL''' field below, enter your X-Cart store's URL.  
 
## From the '''Platform''' drop-down box, select ''X-Cart''. In the '''Store URL''' field below, enter your X-Cart store's URL.  
 
## Click '''Save'''.
 
## 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.  
+
## 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 /><img><br />You should now see the Shipping module configuration page:<br /><img><br />Here you will find 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'''.
+
# 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'''.
# Back in the browser tab where you are using ShippingEasy, copy the Store API Key for your X-Cart store:<br /><img><br />Paste this value into the '''Store API Key''' field on the ShippingEasy module configuration page in your X-Cart store.
+
# 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.
# In ShippingEasy, click on the '''Settings''' tab, then click on the '''API Credentials''' link under '''Account Settings''':<br /><img><br />Your API Key and API Secret will be displayed:<br /><img><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.
+
# 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.
 +
# 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.
 +
<br /><br />
 +
 
 +
==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.<br />[[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.<br />[[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.<br />[[File:shippingeasy_installed.png|border]]
 +
<br /><br />
 +
 
 +
==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'''):<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 />
 +
# 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 />
 +
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.
 +
<br /><br />
 +
 
 +
==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.<br />[[File:export2shippingeasy1.png|border]]<br /><br />The selected orders will be exported to ShippingEasy. A success message will be displayed at the top of the screen:<br />[[File:exported_successfully.png|760px|border]]<br /><br />
 +
* 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.<br />[[File:export2shippingeasy.png|border]]<br /><br />The order will be exported to ShippingEasy. A success message will be displayed at the top of the screen:<br />[[File:exported_successfully.png|760px|border]]<br /><br />
 +
 
 +
==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.<br /><br />
 +
 
 +
==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]]<br /><br />(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).<br /><br />
 +
 
 +
==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".

Latest revision as of 04:37, 6 November 2014

Overview

X-Cart's ShippingEasy module provides integration with ShippingEasy, a cloud-based shipping solution that allows you to automate shipping and lower shipping costs.

ShippingEasy module system requirements and installation

See ShippingEasy module installation.

Integrating your X-Cart store with ShippingEasy

To integrate your X-Cart store with ShippingEasy:

  1. Sign up for an account with ShippingEasy. For detailed information, see the How to create a ShippingEasy account guide on the ShippingEasy website.
  2. If you haven't yet done so, install the ShippingEasy module in your X-Cart store.
  3. 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.
  4. (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:
    1. In the Settings section of your ShippingEasy account, click on the Stores link under Integrations:
      Shippingeasy stores.png

    2. Click the + Add New button on the right-hand side of the screen:
      Shippingeasy add new store.png

      This opens a screen where you will be able to provide the details of your X-Cart store:
      Shippingeasy platform.png

    3. From the Platform drop-down box, select X-Cart. In the Store URL field below, enter your X-Cart store's URL.
    4. Click Save.
    5. 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:
      Shippingeasy store details.png
  5. 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.
    Shippingeasy configure.png

    You should now see the ShippingEasy module configuration page:
    Shippingeasy config settings1.png

    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.
  6. Back in the browser tab where you are using ShippingEasy, copy the Store API Key for your X-Cart store:
    Shippingeasy store api key.png

    Paste this value into the Store API Key field on the ShippingEasy module configuration page in your X-Cart store.
  7. In ShippingEasy, click on the Settings tab, then click on the API Credentials link under Account Settings:
    Shippingeasy api credentials.png

    Your API Key and API Secret will be displayed:
    Shippingeasy api credentials1.png

    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.
  8. 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.
  9. Click the Apply changes button at the bottom of the ShippingEasy module configuration page in X-Cart to save the module configuration.
  10. 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:
<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteRule ^shipment/callback shippingeasy_callback.php
</IfModule>
Important: If your store uses the 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 activate the ShippingEasy module and 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:

  1. Go to the Modules section of your store's Admin area (Settings menu -> Modules). This opens the list of your store's installed modules.
  2. Locate the entry for the ShippingEasy module and select the Enable check box on the left.
    Shippingeasy enable.png
  3. 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.
    Shippingeasy installed enabled.png

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 ShippingEasy module: Uninstallation for more info.

To disable the module:

  1. Go to the Modules section of your store's Admin area (Settings menu -> Modules).
  2. Locate the entry for the ShippingEasy module and unselect the Enable check box on the left.Shippingeasy disable.png
  3. 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.
    Shippingeasy installed.png



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:

  1. In your X-Cart store's Admin area, go to the ShippingEasy statuses page (Settings menu -> ShippingEasy statuses):
    Shippingeasy statuses.png

  2. 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:
    Shippingeasy add status.png

  3. Click Add. The matching statuses will be added to the table above:
    Shippingeasy add status1.png

  4. 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:Shippingeasy add status2.png

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):
  1. 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.
  2. Click the Export to ShippingEasy button at the bottom of the screen.
    Export2shippingeasy1.png

    The selected orders will be exported to ShippingEasy. A success message will be displayed at the top of the screen:
    Exported successfully.png

  • Method 2:
  1. 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.
  2. On the page providing the order's details (Order details page), click the Export to ShippingEasy button.
    Export2shippingeasy.png

    The order will be exported to ShippingEasy. A success message will be displayed at the top of the screen:
    Exported successfully.png

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:

Shippingeasy shipinfo.png

(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".