Ebay integration

The newest version of the user manual for eBay Inventory Manager Module is available here:
eBay User Manual.pdf (module version 2.3.0 for X-Cart versions 4.5.x and 4.6.x)

The manual on this page is an older version intended to users of X-Cart versions 4.3.x-4.4.x.

The eBay Integration Module (also known as the eBay Inventory Manager Module) is a breakthrough in streamlining product management between 2 platforms. The X-Cart Integration for eBay is the fastest and easiest way for business owners to sync product info with eBay automatically, manage eBay inventory from X-Cart, and list items quickly on eBay.

Introduction

This module syncs product info with eBay automatically, allows users to manage eBay inventory from X-Cart, and make updates and list items quickly on eBay. Save time and effort because the eBay integration module maintains inventory and pricing information between 2 different platforms.

Requirements

General

• X-Cart 4.3.x or above

• Users must create or have an active eBay account

• The number of products you can upload is based on your eBay account

Server

• SOAP

• PHP5

• Ioncube

Installation

Normal 0 false false false EN-US JA X-NONE

Instructions

Note: Before installing any module, it is recommended that you backup your database and all X-Cart files

1. Upload all of the files and folders in the .zip file to your root X-Cart directory.
2. Upload your ebay.key file to the newly created /modules/eBay_Inventory_Manager/ directory (You can skip this step if you are installing a trial).
3. Find the patch files that correspond to your version of X-Cart in the .zip file:
   – install_ebay_inventory_manager_4.x.x.patch
   – install_ebay_inventory_manager_4.x.x.sql
4. Upload and run these files via the Patch/Upgrade section of X-Cart.
5. Run cleanup.php to clear your carts cache.
6. Setup the following cron jobs to run on your server, inserting your cart URL where [URL TO CART] appears:

0,30 * * * * /usr/bin/wget -O -q [URL TO CART]/cron_ebay_bulk_jobs.php

• /15 * * * * /usr/bin/wget -O -q [URL TO CART]/cron_ebay_download_orders.php

0 * * * * /usr/bin/wget -O -q [URL TO CART]/cron_ebay_upload_products.php

0 0 * * * /usr/bin/wget -O -q [URL TO CART]/cron_ebay_maintenance.php

That's it! The module should now be installed and ready to configure and use.

Troubleshooting

• Issue #1
  Q: I am getting the following error after installing the eBay Inventory Manager module in my X-Cart store. How do I solve the problem?
  
  Error:
  Warning: file_get_contents(/opt/website/www/modules/eBay_Inventory_Manager/ebay.key): failed to open stream: No such file or directory in /opt/website/www/modules/eBay_Inventory_Manager/config.php on line 0
  
  A: This is a license file which you receive after purchasing the module. To solve the error, this file needs to be placed in the root MODULE folder (i.e. {xcart_dir}/modules/eBay_Inventory_Manager/).
  
  

• Issue #2
  If your cart has been customized, one or more of the patch blocks may have failed, and you will have to modify the cart files manually by following the instructions in the file install_ebay_inventory_manager_4.x.x.html.
  
  

User Manual

Granting Acess to Your eBay Account

Granting Access to Your eBay Account

In order to list products on eBay, you must grant the module permission to make changes to your eBay account. The first time you visit the settings page for the eBay Inventory Manager (eBay Tools > Settings), the following message should appear:

Upon clicking the grant access link, a new window will open prompting you to sign in to your eBay account. After logging in, you will be redirected back to the settings page.

If the link redirects you to a log out page, the authorization link may have expired. Click on the second link to start a new session and retrieve a new login link.

Module Settings

This is a detailed list of the module settings, all of which can be found on the eBay Settings page (eBay Tools > Settings).

eBay Site

This is the eBay site that products will be listed on. Changing this value after listing products on eBay can cause unexpected behavior, and is not recommended.

Currently available sites:

• Australia (https://www.ebay.com.au/)

• United Kingdom (https://www.ebay.co.uk/)

• United States (https://www.ebay.com/)

• US eBay Motors (https://www.motors.ebay.com/)

Currency

Choose the form of currency that you would like your eBay listings to use. Note: the module will not perform any conversion between different X Cart and eBay currencies.

Test Mode

Choose between Sandbox and Production. Use Sandbox mode to test your uploads on the eBay Sandbox site without being charged listing fees.

Default Item Condition

Item condition generally ranges between various forms of New and Used, however the actual display value of the item condition varies depending on the listing category. If products are listed to a category that does not support the condition attribute, this setting is ignored.

Default Listing Duration

Items will be listed for the amount of time shown here. If Relist till goods sold is selected, items will be listed for 30 days, and will automatically be relisted if they have not sold out.

Possible Values:

• 1 day

• 3 days

• 5 days

• 10 days

• 14 days

• 21 days

• 30 days

• 60 days

• 90 days

• 120 days

• Relist till goods sold

Product Price

Choose which product price or membership level price to use for eBay listings. This setting does not affect products with variants, as each variant will be uploaded with its own individual price.

Item Return Time

The buyer can return the item within this period of time from the day they receive the item. If Use product return time is selected, the module will use each product's Product return time value rounded down to the closest acceptable value.

Possible Values:

• Returns not accepted

• Use product return time

• 10 days

• 14 days

• 30 days

• 60 days

Refund Option

If Item Return Time is set to any other value than Returns not accepted, this option indicates how the seller will compensate the buyer for a returned item.

Possible Values:

• Money Back or Exchange - Recommended by eBay if inventory levels permit.

• Money Back

Refund Description

If Item Return Time is set to any other value than Returns not accepted, this area can be used to describe the details of the refund process for eBay listings.

Weight Unit

Choose the weight unit, pounds or kilograms, that you would like your eBay listings to use. The module will convert product weight accordingly if the eBay weight unit differs from the one used in X Cart.

Shipping Paid By

Choose whether you or the buyer will pay the cost of shipping for products listed on eBay.

Shipping Type

This option determines which shipping methods are available for eBay listings.

Possible Values:

• Calculated - You will be using calculated rate shipping methods for both domestic and international buyers.

• Calculated Domestic, Flat International - You will be using calculated rate methods for domestic buyers, but flat rate methods for international buyers.

• Flat - You will be using flat rate shipping methods for both domestic and international buyers.

• Flat Domestic, Calculated International - You will be using flat rate methods for domestic buyers, but calculated rate methods for international buyers.

Use Shipping Table

Use the shipping table defined in your eBay account. For more information, refer to the following page: Using shipping rate tables

Note: Shipping Type must be set to Flat to use this option.

Packaging and Handling Cost

If Flat Rate shipping is selected, this is the default shipping cost for the selected flat rate method. If Calculated shipping is selected, this is an additional handling cost that is added to the shipping total.

International Packaging and Handling Cost

This functions exactly like the option above, but applies specifically to international shipping methods only.

Maximum Dispatch Time

Specifies the maximum number of business days the seller commits to for preparing an item to be shipped after receiving a cleared payment. This time does not include the shipping time (the carrier's transit time).

Default Package Type

Choose the default package type that you will be using when shipping eBay orders. The available values here will vary depending on the eBay site you are connecting to.

International Shipping Locations

Select all international locations that you will ship to. Only select non-domestic locations. If you ship to domestic locations only, please select None.

Domestic Shipping Methods

Shipping methods with 'Flat' or 'Calculated' preceding them are flat rate only, or calculated rate only, respectively. Shipping methods preceded by 'Both' support both the flat rate and calculated shipping type. Choose up to three domestic shipping methods of the same shipping type (i.e. Flat, Calculated, or Both) depending on what value you chose for Shipping Type.

International Shipping Methods

This functions exactly like the option [#Domestic Shipping Methods|above], but with regards to international shipping methods.

Use Your eBay Defined Tax Table

If selected, the module will use the tax table as defined in your eBay account. See Using a tax table.

Tax State

If [#Use Your eBay Defined Tax Table|Use Your eBay Defined Tax Table] is not enabled, choose which state you will be charging tax for here.

Tax Percent

If [#Use Your eBay Defined Tax Table|Use Your eBay Defined Tax Table] is not enabled, choose, enter your states tax percentage here.

Require Immediate Payment

Only select this option if your ONLY method of payment is PayPal.

PayPal Email Address

If using PayPal as a payment method, enter your PayPal email address here.

Payment Methods

Choose which payment methods you will accept for your eBay listings.

Payment Instructions

Use this area to add any additional payment instructions or information for eBay listings.

Title Format

By default, the product title is used for eBay listings, but this field allows you to customize the eBay listing titles.

Available tags:

• [PRODUCT_TITLE]

• [PRODUCT_SKU]

• [MANUFACTURER]

By using these tags, you can customize how your products are displayed in eBay listings. For example, by entering NEW - [PRODUCT_TITLE] - [PRODUCT_SKU] into this field, would change a product title from Green Shirt to NEW - Green Shirt - S0001.

HTML Template Code

This area is similar to the [#Title Format|Title Format] field, but for your actual listing pages. Using several pre-defined tags, you can create a listing template with dynamic product information for all of your products.

Available tags:

• [PRODUCT_IMAGE]

• [PRODUCT_TITLE]

• [PRODUCT_DESCRIPTION]

• [PRODUCT_SHORT_DESCRIPTION]

• [PRODUCT_LONG_DESCRIPTION]

• [PRODUCT_SKU]

• [ADDITIONAL_IMAGES]

• [MANUFACTURER]

Detailed Images Template

Advanced use only! Use this field to customize how detailed product images are output to the listing template via the [ADDITIONAL_IMAGES] tag in your [#HTML Template Code|template code].

Available tags:

• [IMAGE_N] - The index number of the current detailed image

• [IMAGE_URL] - The URL value of the current detailed image

Automatically Upload Valid and Mapped Products

If selected, the module will attempt to upload any unlisted products that are in a correctly mapped X Cart category.

Enable Mapping to Custom eBay Categories

Choose this option if you have an eBay store, it will enable you to map your X Cart categories to your custom categories.

Main Listing Image

Choose whether to upload the Thumbnail or Product Image as the main product image for your listings.

Create User Accounts in X-Cart for New eBay Customers

If enabled, the module will create an X Cart customer account for each new eBay buyer. New buyers will receive an email notification with a username and temporary password to access their new account on your site.

Include Detailed Images in Listing

If enabled, detailed images will be uploaded with products as additional listing images. Not applicable to products with variants. Note: If more than one image per product is used, all listing images must be hosted using eBayís Picture Hosting Services. This significantly increases the upload time for products, and can potentially cause large bulk uploads to fail.

Remove Items from eBay When QTY Reaches

eBay listings will be automatically ended when they reach the quantity specified here. If this option is left blank, listings will be ended automatically when quantity reaches 0.

Mapping Mode

The module can map X Cart categories in two different ways. Assign multiple X Cart to single eBay category should be used if you have multiple X Cart categories that all belong to one eBay category. Alternatively, if you would prefer to assign a separate eBay category to each X Cart category, Assign single eBay to each X Cart category should be used. The latter option is a bit more complicated to set up initially, but does offer more control over the category mappings. Note: Changing this value will reset any category mappings that you have set up. See Mapping X-Cart Categories to eBay Categories for more information on category mappings.

Image Trigger Class

Choose which variant class will control the variant images for eBay listings.

Order Insert Status

Advanced use only! Use this field to specify the default initial order status of orders downloaded from eBay. If empty, orders will be downloaded as 'P' (Processed). This setting is useful if you have added custom order statuses to your cart.

Do not adjust selected fields

Fields selected in this option will not be updated when products are revised or relisted. This is useful if you want to change your X Cart data without affecting existing eBay listings.

eBay Categories

The eBay Inventory Manger uses a category mapping system to associate your categories in X Cart to their respective categories on eBay. This system allows you to quickly assign eBay listing categories to your products without having to modify each product individually.

For example, letís say that you sold cell phones, and all of your cell phones are in the X Cart category Cellular Phones, which is located under the root category Electronics (i.e. Electronics / Cellular Phones). You want to list all of the products in your Cellular Phones category in the Cell Phones & Smartphones eBay category, located under the root eBay category Cell Phones & Accessories (i.e. Cell Phones & Accessories / Cell Phones & Smartphones). Using the Map X-Cart Categories to eBay Categories page, you would assign, or map, Electronics / Cellular Phones from X-Cart to Cell Phones & Accessories / Cell Phones & Smartphones on eBay.

Enabling eBay Categories

Enabling eBay Categories

The first step to mapping categories is enabling the eBay categories that you want to map to. The Map X-Cart Categories to eBay Categories page lists every category on the currently selected eBay site. Click on a category to see its subcategories. To return to the previous page, click on Go up a level or hit the back button on your browser.

Products can only be uploaded to leaf categories, i.e. categories have no subcategories of their own. A leaf category will not be clickable, and it will have a checkbox available in the Enabled column. Check this box and click the Update button below the category list to enable a category.

Mapping X-Cart Categories to eBay Categories

Once an eBay category has been enabled it will appear below the eBay category list on the Map X-Cart Categories to eBay Categories page. To remove an eBay category from this area, check the box in the Disable column, and click Save. There are two different ways to map X Cart categories to eBay categories:

Fig. 1
In this example, all products from the X Cart categories Electronics and Electronics/Cellular Phones will be listed in the eBay category Cell Phones & Accessories / Cell Phones & Smartphones and the store categories Electronics and Electronics/Cellular Phones.

Fig. 2
In this example, all products from the X Cart category Books will be listed in the eBay category Dolls & Bears/Bears/Gund and the store category Books.

Assigning Multiple X-Cart Categories to a Single eBay Category

The first mapping method available allows you to assign multiple X Cart categories at one time, making it a very fast way to map your categories.

You can select as many X Cart categories on as you like, and they will all be mapped to the eBay category shown on the right. You can also choose a secondary eBay category to list your products in, although some category combinations may be incompatible. If you have an eBay store and have checked the setting Enable mapping to custom eBay categories, you can also choose which of your store categories products will be listed in.

Once you have made your selection, click Save. See Fig. 1

Assigning Single eBay Category to Each X Cart Category

This method of mapping categories requires more work, but gives you more control over what categories your products are being listed under on eBay.

Here each X Cart category is listed alphabetically, along with Primary and secondary category selectors for eBay categories. If you have an eBay store and have checked the setting Enable mapping to custom eBay categories, you can also choose which of your store categories products will be listed in. Once you have made your selection, click Save. See Fig. 2

Overriding Category Mappings

If you find that you need even more granular control over which categories your products are listed in on eBay, you can set the eBay category per product and override that products category mapping. This can be done by adjusting the eBay Category dropdown menu on the X-Cart Product Modify page.

Listing an Item

Once you have mapped an X-Cart category to an eBay category, you are ready to start listing products. Below you will find various ways to list products.

Listing Single Products

From the Upload Products page

If automatic uploads are disabled, products from X-Cart can be uploaded to eBay manually from the Upload Products page (eBay Tools > Upload Products). This page shows all products that are in categories mapped to eBay categories. If a product is missing important information, an alert icon will be present in the right most column. See Listing Errors for more information on these alerts.

From this page, you are able to list single products by clicking on Upload. If the product has been listed before, the Relist link will be available. You can click on Relist to maintain your eBay search rankings and meta information instead of creating a new listing.

After listing a product, either by clicking Upload or Relist, you will receive a success confirmation in the upper right corner of the screen. If an error occurs, a notice will be displayed with error information.

From the Product Modify page

Products that are ready to be listed will also have a series of listing control buttons on the bottom of X-Cart's Product Modify page in the admin area.

Listing Multiple Products

In addition to listing products one at a time, products can be listed in bulk. To list multiple products, check the box next to the SKU column, and then click the Upload at the bottom of the page. This will create a bulk upload job, which you can check the status of on the eBay Bulk Jobs page.

Listing Products Automatically

If the option Automatically Upload Valid and Mapped Products is enabled, the module will check for new products to upload every hour.

Managing Listings

Viewing Listings

Once a product has been successfully listed on eBay, you can view the actual listing several different ways:

From the Products on eBay page

This page shows all products in your store that are listed on eBay. To view a listing, click on the Listing page link on the corresponding line.

Note: When you first use the module, you may not initially see your pre-existing eBay listings on this page. Clicking on the link at the top of the page will make the module search through your active listings for SKUs that exist in your cart.

From X-Cart Search Pages

Products that are returned from X-Cart searches in the admin area will have a Listing page link with the eBay logo next to them if they are currently listed.

From the Product Modify page

The listing controls at the bottom of the page will contain a View Listing button on the Product Modify page if the product is currently listed.

Revising Listings

Listing information is automatically updated in real time when it is changed in X-Cart. This includes modifying product information from the admin area, and updating quantity when products are purchased on your X-Cart store.

If the database is modified outside of X-Cart (e.g. by a third party application), or if changes are made to the module settings that affect all products (e.g. the html template code), you can update all of your listings at once by navigating to the Products on eBay page and clicking the Update All Listings button.

If for some reason one product becomes out of sync, you can update it individually by clicking the Update link on the Products on eBay page, or the Update Listing button on the bottom of the Product Modify page.

Ending Listings

Listings will be ended automatically when product inventory reaches 0 or whatever value is entered in the Remove Items from eBay When QTY Reaches setting.

From the Products on eBay page

Items can be ended manually from this page by clicking the Remove link on the corresponding line. Alternatively, multiple listings can be ended by checking the box next to the product SKU and clicking on the Remove button.

From the Product Modify page

Listings can also be ended manually from the Product Modify page by clicking on the End Listing button at the bottom of the page.

Downloading Orders

eBay orders are downloaded automatically into X-Cart every 15 minutes and decrement product quantities accordingly, they require no manual action. eBay orders function exactly the same as regular X-Cart orders, but contain an eBay order id and sales record number.

If Create User Accounts in X-Cart for New eBay Customers is enabled, customer accounts will be created for eBay orders from new users. Otherwise, the orders will appear as anonymous checkout orders (i.e. orders from users that did not login to your store).

Listing Errors

If a product is configured incorrectly in X-Cart, or does not conform to an eBay listing rule, the module will do its best to resolve the problem automatically. Sometimes, however, user action is required and in these cases the module will display informational messages explaining the conflict.

Before Listing

Before attempting to upload a product to eBay, the eBay Inventory Manager will run a preliminary check on the product data, and report back any missing or incorrect information. This information can be seen by hovering the mouse cursor over the notification icon in the right most column on the Upload Products page (eBay Tools > Upload Products).

A red circle with an ëxí indicates that critical information is missing from the product, and it cannot be uploaded to eBay until the items listed in the popup notification are taken care of.

A yellow triangle with an exclamation point means that there is information missing that is recommended, but not necessarily required. In most cases, these products will upload successfully, however there are situations where the extra data is necessary. For example, some shipping methods require an items length, width, and height to be specified.

A green checkmark indicates that the product has passed the preliminary check successfully and is ready to be uploaded.

Listing Failures

Sometimes an even though an item has passed the preliminary check, the upload can still fail due to one of eBayís listing policies. When this happens, an error notification will appear at the top of the page.

Errors from bulk jobs will return a list of SKUs that were rejected by eBay. Uploading these products individually

will return a more detailed error explaining why the upload failed.

Troubleshooting

Downloading missed orders from eBay

If orders are not downloading from eBay, you may need to re-trigger them for download. (A possible problem is mysql being down. Once mysql is running again, order downloads will resume.)

Manually trigger an order download by modifying orders. You can add tracking or comments to trigger a download. Update tracking information for your eBay orders. The module will check for new orders within an hour time frame, if any are missed due to an outage, touch the order (which will change the date), by adding comments or the tracking information, etc.