Commerce Ebay

Synopsis

Ebay Commerce facilitates the listing of Drupal Commerce products on Ebay, and automated stock management. The module uses a YAML config file, to define a feed which is then transposed by a Mapping class, which fills in all of the values with either plain text, node data or product variation data. A sample file is provided with a production working example which can then be tailored to suit any extra needs. Variations, Variation Specifics and Variation Pictures have additional processing in the mapping to get these to map correctly.

The module is set to run on an interval, items can be queued using a Queue All Items button in the admin settings for the first time, after that, any items will sync automatically should a quantity change locally or on ebay.

Both Sandbox and Production settings can be use in the case of testing, which is the recommended method before going straight ahead with a live feed.

A sample XML feed is also available, which will allow the testing of a few feeds, which will transpose the mapping file to a node, great for testing.

Requirements

Drupal Commerce must be installed and enabled for the module to work.

Elysia Cron is also a requirement, which handles the routine synchronisation of stock and listings.

Known problems

The feed mapping, while it is fairly robust, it does not contain a looping method, so fields must me mapped to single values unless the field value returns an array. The feed mapping has an ability to pass a returned field value into a function. For instance, to map a variation field, obtain a nested value within the entity and then pass it through a number_format function, the following can be mapped in the YAML file:
$field_product_dimensions$->width|number_format($context, 2);
however as the regular expression to extract the function portion grabs the function first, and then anything inside the brackets is split by comma and passed into a reflection method, this means that if an array or anything requiring an apostrophe is passed into that function i.e. $field_product_dimensions$->width|some_function($context, array(2,3,4)); it's not going to work. The function processing really was meant for simple string parameters, all parameters are expected to be strings or ints, so no commas are necessary.

The module only handles "Add Fixed Price Item", "Revise Fixed Price Item", "Get Item" and "End Fixed Price Item" feed functions, although other functions are present within the Trading class as they may be used at another time. So anything like reporting or other API calls would require extending the Service class and using the Trading class as an example.

eBay only allows a certain amount of items to be uploaded depending on the account type, this usually is a stock price limit i.e. no more than $1000 worth of stock, or some other limit. Keep this in mind and be aware before attempting to list all of your items, as this will show up in the logs if you've gone over that limit.

Most issues, virtually all issues you will encounter, will stem from the eBay service itself, as it is extremely picky about how the XML is formatted. Any missing required fields or accidentally placed fields or invalid values will cause a feed upload to fail. The sample YAML file is a production sample feed, which was laboured over intensively to overcome a lot of the initial errors coming from eBay.

Similar projects and how they are different

Ebay Integration Module This module allows the creation of a special Ebay Product type. This module was originally going to be used for the project Ebay Commerce was built for, however it didn't fulfil the requirements. Ebay Commerce doesn't require any special product types to be created, as it simply transposes a YAML file with existing products and product types to an XML feed.
Ebay IntegrationAnother eBay integration module is done here, however it's exact function isn't as clear on the module page.

Dependencies

Spyc is required for the module to run. It can be installed using composer and the included composer.js file, or it can be installed from the following repository: https://github.com/mustangostang/spyc/ It must be placed into the following directory within the module libraries/mustangostang/spyc
Array2XML is required for the module to run. The commerce-ebay branch MUST be used, master will not work. It can be installed using composer and the included composer.js file, or it can be installed from the following repository manually: https://github.com/nonapod/Array2XML It must be placed into the following directory within the module libraries/nonapod/Array2XML/strong>

Restrictions

The module uses product Variations, there is no current alternative with the module. Meaning that you will need to map your categories to eBays Variation allowed categories, you can find them here: Variation Allowed Categories

The feed mapping, while it has most of the requirements covered, there may be a few use cases where more rigorous processing is needed. For instance in the case of variations, variation specifics and photos for variations, additional processing is done in the mapping module to take the specifics for a particular variation, and copy them up a level into a unique array. Likewise with photos, photos are done on a variation specific basis, so extra processing is done.

The feed mapping is done once per product display. If you have say 2 node types each with product fields within and want them both to go to eBay i.e. a service display node and a product display node. The feeds will need to be defined individually for each of these node types. This may just end up being a simple copy and paste however be aware that the more node types you have for listing products and want on eBay, you will have to define those feeds separately for each one, meaning the YAML file could grow in size, so using Comments in the YAML, like is done in the sample, will be the best way for keeping good track of each mapping.

The module uses Array2XML; the YAML is pulled in as an object, which is then parsed, values are replaced and then the result of that is fed to Array2XML, so the YAML format must obey the restrictions of that module i.e. to have multiple ShippingDetails fields:

<ShippingDetails>...</ShippingDetails>
<ShippingDetails>...</ShippingDetails>
<ShippingDetails>...</ShippingDetails>

They need to be defined something like this in the YAML file (Note that the sample YAML file has a lot of commenting in it to help with set up):

ShippingDetails:
  -
    ShippingType: "Calculated"
    ...
  -
    ShippingType: "Calculated"
    ...
  -
    ShippingType: "Calculated"
    ...

Check here for information on the Array2XML module: http://www.lalit.org/lab/convert-php-array-to-xml-with-attributes/

Categories are mapped twice: Once for eBay categories, and once for Store categories. This is done in the YAML mapping files. Category mapping looks like the following example:

Category Mapping:
  # a $default category should always be set as a fallback
  $default: 165942
  Clearance: 165943
  ....
Store Category Mapping:
  # a $default category should always be set as a fallback
  $default: 0
  Clearance: 3234
  ....

You will need to find out the IDs of the categories which can be found either in the eBay resources or at a site like this one: Easy eBay Category Numbers

For Store Categories you will have to set them up manually on eBay and manage them there, inputting the IDs in the YAML. Otherwise items will be placed into the "Other" store category by default.

In one iteration categories were mapped with a different process that would allow a drop down when editing an eBay flagged taxonomy, which would also sync store categories back and forward together. However this felt very clunky and a lot of the code ended up being purely to keep categories synced back and forwards. The mapping file approach felt more natural, less prone to error and in tune with the nature of the module, and thus the GUI based automated category mapping/syncing was removed.

Resources

There are a lot of resources to check. The YAML and README.txt will contain most of the resources listed below, and more.

If you are using this module it is assumed you're trying to get a feed set up for either yourself or a client and are already somewhat familiar with the eBay developer docs. First check out the eBay Developers Program. Next you should create a sandbox PayPal and eBay account with eBay to test the module using the sandbox. You will also need to acquire the necessary tokens, you can find out which tokens you will need by checking out the Admin settings for the module: admin/commerce/config/ebay

When mapping variations, you should check for Variation Allowed Categories, as this module is set to only use variations:

Check the following links for information on fields that can be mapped for the Add Fixed Price Item and Revise Fixed Price Item Feeds.
http://developer.ebay.com/devzone/xml/docs/reference/ebay/AddFixedPriceItem.html
http://developer.ebay.com/devzone/xml/docs/reference/ebay/revisefixedpriceitem.html