WP-Lister for eBay API – Hooks and Filters

Contents

If you are a developer writing a plugin or theme for WP-Lister for eBay, you might find the following filters and actions hooks useful.

Note: This documentation is work in progress and doesn’t cover all available hooks yet.

If you want us to add a specific hook to help in your particular use case, don’t hesitate to contact us. We appreciate all suggestions and will usually implement your request in the next update.

Where to add custom code snippets

The standard location to add custom code snippets like some of the examples below would usually be the functions.php file contained in your current WordPress theme. This can become a problem when you need to update your theme, which would overwrite that functions.php file, meaning you would loose all your custom code snippets.

That’s why it’s generally recommended to use a child theme when you want to add or modify any code of your theme, but some commercial themes are already child themes and still need to be updated eventually, which is why we highly recommend a custom plugin as the location for all your custom code snippets.

Unless you’re a developer who prefers to write something similar yourself, please take a look at our WP Lab Custom Code plugin. This one is meant to be “A handy little plugin to contain your custom code snippets” and is used by our support staff whenever we need to install some custom code on a client’s site. If you are looking for a more comprehensive solution that supports not only custom PHP snippets but also CSS, JavaScript and template overrides, please check out the Theme Customisations plugin created by the people from WooCommerce.

wplister_revise_inventory_status

Call this action after you have changed the price or stock level of a WooCommerce product. It will send a ReviseInventoryStatus requests to eBay, which will update price and inventory but leave all other details untouched.

Usage

$new_stock = 5;
update_post_meta( $post_id, '_stock', $new_stock );
do_action('wplister_revise_inventory_status', $post_id );

wple_revise_inventory_status_skip_price

This filter tells WP-Lister to omit the price when sending a ReviseInventoryStatus request to eBay. This only works on locked listings.

add_filter( 'wple_revise_inventory_status_skip_price', 'wplister_skip_price_update', 10, 3 );
function wplister_skip_price_update( $skip, $listing_id, $listing_item ) {
    // return TRUE to skip price update
    return true;
}

wplister_revise_item

This will send a ReviseItem request to eBay, which will update all item details. Use it when you need to update details other than price and stock level. Revising an item is considerably slower than revising the inventory status, so if you have to change many listings at once, consider using wplister_product_has_changed and clicking the Revise all changed items button in the UI.

Note: A listing will end when it is revised with a quantity of zero.

Usage

update_post_meta( $post_id, '_ebay_subtitle', 'Your listing subtitle' );
do_action('wplister_revise_item', $post_id );

wplister_relist_item

Relist an ended listing on eBay with this call. This might be required if you change an out of stock product to be in stock again, as a listing will be automatically ended when its quantity reaches zero – so if you are changing a product from out of stock to have stock again, you need to tell WP-Lister to relist the ended listing.

Usage

do_action('wplister_relist_item', $post_id );

wplister_end_item

This will end a listing on eBay. Accepts an eBay Item ID or a $listing_id as parameter. To end a specific $post_id, fetch the $listing_id as shown in the example below. Available since 2.0.9.10.

Usage

// end listing by eBay Item ID
do_action('wplister_end_item', $ebay_id ); // $ebay_id = 123456789012

// end listing by Product ID
$post_id    = 123;
$listing_id = WPLE_ListingQueryHelper::getListingIDFromPostID( $post_id );
do_action('wplister_end_item', $listing_id );

wplister_prepare_listing

Prepare a new listing from a WooCommerce product and apply a profile. This hook is available in version 1.5.0.5+.

Usage

do_action('wplister_prepare_listing', $post_id, $profile_id );

wplister_product_has_changed

Mark a product as changed in WP-Lister. Use this if you need to emulate how WP-Lister behaves when a product is updated manually in WooCommerce: The profile will be reapplied to update dynamic prices and custom quantities, but the listing is not updated on eBay right away – instead, its status is set to changed and WP-Lister will prompt the user to Revise all changed items.

Usage

do_action('wplister_product_has_changed', $post_id );

Example: How to add custom support for third party plugin

As a more real live example, let’s assume you have a third party plugin or script updating prices of your products on a daily basis. Let’s further assume that this plugin doesn’t provide any specific action hooks to hook into, but simply uses the update_post_meta() function to update prices like this:

update_post_meta( $post_id, '_regular_price', $new_price );
update_post_meta( $post_id, '_price', $new_price );

Unfortunately this isn’t enough to notify WP-Lister that the product has been changed. However, we can hook into an action hook provided by WordPress itself, which is triggered when any post meta field is updated:

add_action( 'updated_postmeta', 'my_action_wplister_updated_product_price', 10, 4 );
function my_action_wplister_updated_product_price( $meta_id, $post_id, $meta_key, $meta_value) {
 if ( $meta_key == '_price' ) {
  // For variable products, we need to pass the parent ID
  if ( $parent_id = ProductWrapper::getVariationParent( $post_id ) ) {
    $post_id = $parent_id;
  }

  do_action( 'wplister_product_has_changed', $post_id );
 }
}

Just make sure you use the meta key which is updated last – which is _price in this case – so if for example your plugin would update stock levels after updating the price, you should use _stock instead.

wple_custom_attributes

This filter allows you to use custom post meta data that might exist in your wp_postmeta table like a WooCommerce attribute which can be mapped to item specifics required by eBay.

The example below is taken from WP-Lister itself and it is used to make the SKU available for item specifics.

Usage

add_filter( 'wple_custom_attributes', 'my_filter_wplister_custom_attributes' );
function my_filter_wplister_custom_attributes( $attributes ) {
 $attributes[] = array(
 'label'    => 'SKU',
 'id'       => '_sku',
 'meta_key' => '_sku'
 );

 return $attributes;
}

The next example adds the option to select “N/A” as a fixed value. (available since version 2.0.9.4)

Example #2

add_filter( 'wple_custom_attributes', 'my_filter_wplister_custom_attributes' );
function my_filter_wplister_custom_attributes( $attributes ) {

 $attributes[] = array(
 'label'    => 'N/A',
 'id'       => '_na',
 'value'    => 'N/A'
 );

 return $attributes;
}

The next example assumes you have a custom taxonomy “product_brand” and adds the option to select “Brand (Taxonomy)” as an attribute when editing a profile. (available since version 2.0.9.6)

Example #3

// add custom attribute to WP-Lister
add_filter( 'wple_custom_attributes', 'my_filter_wplister_custom_attributes' );
function my_filter_wplister_custom_attributes( $attributes ) {

 $attributes[] = array(
 'label'    => 'Brand (Taxonomy)',
 'id'       => '_my_brand',
 'callback' => 'my_filter_wplister_get_brand_name'
 );

 return $attributes;
} 

// get brand name for product (callback function)
function my_filter_wplister_get_brand_name( $post_id, $listing_id ) {

 // get array of brands (taxonomy terms) for $post_id
 $brands = get_the_terms( $post_id, 'product_brand' );
 if ( ! is_array($brands) ) return '';
 if (   empty($brands)    ) return '';

 // return name of first brand
 return $brands[0]->name;
}

wple_process_template_html

This filter allows you to process the listing description HTML after the template was applied.

You can use this to implement custom shortcodes as shown below:

Usage

add_filter( 'wple_process_template_html', 'my_filter_wplister_process_template_html', 10, 3 );
function my_filter_wplister_process_template_html( $html, $item, $images ) {
 $html = str_replace( '[[my_custom_listing_shortcode]]', 'MY CUSTOM CONTENT', $html );
 return $html;
}

Example #1 – Sale Price

// add custom shortcode to display the sale price
add_filter( 'wple_process_template_html', 'my_filter_wplister_process_template_html', 10, 3 );
function my_filter_wplister_process_template_html( $html, $item, $images ) {
    $special_price = get_post_meta( $item['post_id'], '_sale_price', true );
    $special_price_html = '';
    if ( $special_price ) {
        $special_price_html = 'Sale Price: '.woocommerce_price( $special_price );
    }
    $html = str_replace( '[[special_price]]', $special_price_html, $html );
    return $html;
}

Example #2 – Original Product Name

// add custom shortcode to display the original post title from WordPress / WooCommerce
add_filter( 'wple_process_template_html', 'my_filter_wplister_process_template_html', 10, 3 );
function my_filter_wplister_process_template_html( $html, $item, $images ) {
    $post_title = get_the_title( $item['post_id'] );
    $html = str_replace( '[[post_title]]', $post_title, $html );
    return $html;
}

Example #3 – List all Product Attributes

// list all product attributes names and values
// usage: [[product_attributes_list]]
add_filter( 'wple_process_template_html', 'my_wplister_template_filter_product_attributes_list', 10, 3 );
function my_wplister_template_filter_product_attributes_list( $html, $item, $images ) {

    $post_id    = $item['parent_id'] ? $item['parent_id'] : $item['post_id'];
    $attributes = ProductWrapper::getAttributes( $post_id );

    $attributes_list = '';
    foreach ($attributes as $name => $value) {
        $value = str_replace( '|', ', ', $value );
        $attributes_list .= $name . ': ' . $value . '<br>';
    }

    $html = str_replace( '[[product_attributes_list]]', $attributes_list, $html );
 return $html;
}

Example #4 – Product Reviews

// add custom shortcode to display product reviews from WooCommerce on eBay
add_filter( 'wple_process_template_html', 'my_filter_wplister_process_template_html', 10, 3 );
function my_filter_wplister_process_template_html( $html, $item, $images ) {

    // get all approved comments
    $comments = get_comments( array( 'post_id' => $item['post_id'], 'status' => 'approve' ) );
    if ( empty( $comments ) ) return $html;

    // build reviews html
    $reviews_html  = '<h3>Reviews</h3>';
    $reviews_html .= '<ul class="product_reviews">';
    foreach ($comments as $comment) {
     $reviews_html .= '<li>';
     $reviews_html .= $comment->comment_content;
     // show author and date - remove if you like
     $reviews_html .= '<br><small><i>'.$comment->comment_author.' on '.date(get_option('date_format'),strtotime($comment->comment_date)).'</small></i>';
     $reviews_html .= '</li>';
    }
    $reviews_html .= '</ul>';

    // replace shortcode with generated html
    $html = str_replace( '[[product_reviews]]', $reviews_html, $html );

    return $html;
}

Example #5 – Support for WooCommerce Tab Manager

// implement custom listing shortcodes for product tabs
// http://www.woothemes.com/products/woocommerce-tab-manager/
// usage: [[product_tab_tabname_title]] or [[product_tab_tabname_content]]
function wplister_template_filter_process_product_tabs( $html, $item, $images ) {

    // fetch custom tab meta info
    $_product_tabs = get_post_meta( $item['post_id'], '_product_tabs', true );
    if ( ! $_product_tabs || ! is_array( $_product_tabs ) ) return $html;
    // echo "<pre>";print_r($_product_tabs);echo"</pre>"; // uncomment to debug

    // loop product tabs
    foreach ( $_product_tabs as $key => $tab ) {

        // load tab post for product tabs
        if ( ! in_array( $tab['type'], array( 'product', 'global' ) ) ) continue;
        $tab_post = get_post( $tab['id'] );
        if ( ! $tab_post ) continue;

        // replace shortcodes
        $tab_id = $tab['name'];
        $html = str_replace( '[[product_tab_'.$tab_id.'_title]]',   $tab_post->post_title,            $html );
        $html = str_replace( '[[product_tab_'.$tab_id.'_content]]', wpautop($tab_post->post_content), $html );

    }

    return $html;
}
add_filter( 'wple_process_template_html', 'wplister_template_filter_process_product_tabs', 10, 3 );

Example #6 – eBay Primary Category ID

// add custom shortcode to insert the numerical eBay Primary Category ID
// Note: this example requires WP-Lister version 2.0.9.17 or better
// usage: [[ebay_primary_category_id]]
add_filter( 'wple_process_template_html', 'my_filter_wplister_process_template_html', 10, 4 );
function my_filter_wplister_process_template_html( $html, $item, $images, $ItemObj ) {
    if ( ! $ItemObj ) return $html;
    $primary_category_id = $ItemObj->PrimaryCategory->CategoryID;
    $html = str_replace( '[[ebay_primary_category_id]]', $primary_category_id, $html );
    return $html;
}

Example #7 – Large Featured Product Image

// add custom shortcode to insert the "large" version of the featured image
// usage: [[product_large_image]]
add_filter( 'wple_process_template_html', 'my_filter_wplister_process_template_html', 10, 3 );
function my_filter_wplister_process_template_html( $html, $item, $images ) {
    $large_image = '';
    $large_image_url = wp_get_attachment_image_src( get_post_thumbnail_id( $item['post_id'] ), 'large' );
    if ( ! empty($large_image_url) ) {
        $large_image = '<img class="wpl_product_image" src="'.$large_image_url[0].'" alt="main image" />';
    }
    $html = str_replace( '[[product_large_image]]', $large_image, $html );
    return $html;
}

wple_get_product_main_image

Use this filter to define a custom main product image for your listings. This can be useful in many cases, including a site that uses transparent PNG images on the website, which unfortunately are not compatible with eBay.

The example below assumes that you are using the Advanced Custom Fields plugin (ACF) and have created a custom field called “ebay_product_image” in order to override the default featured image on eBay.

Usage

add_filter( "wple_get_product_main_image", "my_custom_ebay_product_main_image", 10, 2 );

function my_custom_ebay_product_main_image( $image_url, $post_id ) {
    // Check if a custom eBay image is set with ACF
    $ebay_image = get_field( 'ebay_product_image', $post_id );
    $image_url  = $ebay_image ? $ebay_image : $image_url;
    return $image_url;
}

wple_ebay_price

Use this filter to apply a custom rounding function to the price on eBay. This can be useful if you have set a percentage in your listing profile but don’t want to have “odd” decimals (cents).

Usage

add_filter( "wple_ebay_price", "my_custom_ebay_rounding_function" );

function my_custom_ebay_rounding_function( $price ) {
    $price = round( $price ); // this will round the amount to a whole number
    return $price;
}

wple_set_tracking_number_for_order

This filter allows you to automatically populate the eBay tracking number on an order details page. Available since version 1.5.0.5.

Usage

add_filter( "wple_set_tracking_number_for_order", "my_custom_ebay_tracking_number", 10, 2 );

function my_custom_ebay_tracking_number( $tracking_number, $post_id ) {
    // if no tracking number is set, pull value from _alternate_tracking_number custom field
    if ( ! $tracking_number ) {
        $tracking_number = get_post_meta( $post_id, '_alternate_tracking_number', true );
    }
    return $tracking_number;
}

wple_set_shipping_date_for_order

This filter allows you to automatically populate the eBay shipping date field on an order details page. Available since version 1.6.0.2.

Usage

add_filter( "wple_set_shipping_date_for_order", "my_custom_ebay_shipping_date", 10, 2 );

function my_custom_ebay_shipping_date( $shipping_date, $post_id ) {
    // if no shipping date is set, pull value from _alternate_shipping_date custom field
    if ( ! $shipping_date ) {
        $shipping_date = get_post_meta( $post_id, '_alternate_shipping_date', true );
    }
    return $shipping_date;
}

wple_set_shipping_provider_for_order

This filter allows you to automatically populate the eBay shipping provider field on an order details page. Available since version 1.6.0.2.

Usage

add_filter( "wple_set_shipping_provider_for_order", "my_custom_ebay_shipping_provider", 10, 2 );

function my_custom_ebay_shipping_provider( $shipping_provider, $post_id ) {
    // if no shipping provider is set, pull value from _alternate_shipping_provider custom field
    if ( ! $shipping_provider ) {
        $shipping_provider = get_post_meta( $post_id, '_alternate_shipping_provider', true );
    }
    return $shipping_provider;
}

wple_available_shipping_providers

This filter allows you to customize the list of available shipping providers on the order details page. Available since version 1.5.0.6.

Usage

add_filter( "wple_available_shipping_providers", "my_custom_ebay_shipping_providers", 10, 1 );

function my_custom_ebay_shipping_providers( $shipping_providers ) {
    // define custom selection of shipping providers
    $shipping_providers = array(
        'FedEx' => 'Fedex',
        'UPS'   => 'UPS',
        'USPS'  => 'U.S. Postal Service',
        'Other' => 'Other postal service'
    );
    return $shipping_providers;
}

wple_order_builder_line_item

This hook allows you to modify the data that will be used to create order line items in WooCommerce.

The sample code below pulls the actual product title from WooCommerce instead of using the eBay item name.

add_filter( 'wple_order_builder_line_item', 'my_wple_line_item_title', 10, 2 );
function my_wple_line_item_title( $order_item, $order_id ) {
    if ( $order_item['product_id'] > 0 ) {
        $order_item['name'] = get_the_title( $order_item['product_id'] );
    }
    return $order_item;
}

wple_complete_order_data

This hook allows you to modify the data that will be provided to eBay when marking an eBay order as complete and is especially useful when you need to submit custom tracking information to eBay.

The sample code below pulls the tracking information from the YITH WooCommerce Order Tracking plugin.

add_filter( 'wple_complete_order_data', 'wple_insert_custom_tracking', 10, 3 );
function wple_insert_custom_tracking( $data, $order_id ) {
    // if no tracking number is set, pull value from ywot_tracking_code custom field
    if ( empty( $data['TrackingNumber'] ) ) {
        $data['TrackingNumber'] = get_post_meta( $order_id, 'ywot_tracking_code', true );
    }

    // if no shipping date is set, pull value from ywot_pick_up_date custom field
    if ( empty( $data['ShippedTime'] ) ) {
        $data['ShippedTime'] = get_post_meta( $order_id, 'ywot_pick_up_date', true );
    }

    if ( empty( $data['TrackingCarrier'] ) ) {
        $yith_courier = get_post_meta( $order_id, 'ywot_carrier_id', true );
        if ($yith_courier == 'ROYAL_MAIL')
            $data['TrackingCarrier'] = 'Royal Mail';
        if ($yith_courier == 'DPD_LOCAL_UK')
            $data['TrackingCarrier'] = 'interlinkexpress';
    }

    return $data;
}

wple_after_create_order_with_nonexisting_items

Use this action hook if you need to post process WooCommerce orders that were created by WP-Lister. The example below will remove the email address from the WooCommerce order, which might be useful if you want to make sure that no other plugins (like the Follow Up Emails extension) could accidentally send emails to the email address provided by eBay.

Important: If you use this hook to process order line items, please keep in mind that WP-Lister might create orders for products which do not exist in WooCommerce! That is the reason why we named the hook this way: Not because it would only fire for non-existing products, but because it can. And if your code does not expect this, it might break the synchronisation of sales or worse.

Usage

add_action( 'wple_after_create_order_with_nonexisting_items', 'my_wple_after_create_order_action' , 10, 1 );
function my_wple_after_create_order_action( $post_id ) {
    // remove email address from order
    update_post_meta( $post_id, '_billing_email', '' );
}

wple_filter_listing_item

Use this filter to manipulate listing data before it is sent to eBay during a AddItem or ReviseItem request. This feature is very powerful and should be used carefully. Available since version 1.5.0.2.

Usage

add_filter( "wple_filter_listing_item", "my_custom_ebay_listing_filter", 10, 4 );

function my_custom_ebay_listing_filter( $item, $listing, $profile_details, $post_id ) {
    // the code below is only intended for documentation purposes
    $item->Title .= ' - append something to your listing title';
    $item->PayPalEmailAddress = 'overwrite paypal email address';
    return $item;
}

wple_local_shipping_services

wple_international_shipping_services

Filter local and international shipping services sent to eBay during a AddItem or ReviseItem request. The example below removes a specific shipping service if the product weight is greater than 13oz. Available since version 2.0.9.8.

Usage

// remove a specific shipping service depending on product weight
add_filter( 'wple_local_shipping_services', 'my_shipping_service_filter', 10, 4 );
add_filter( 'wple_international_shipping_services', 'my_shipping_service_filter', 10, 4 );

function my_shipping_service_filter( $services, $post_id, $actual_post_id, $listing ) {

  // check if weight is above 13 oz = 0.8125 lbs
  $weight = ProductWrapper::getWeight( $actual_post_id ) ;
  if ( $weight > 0.8125 ) return $services;

  // remove USPSFirstClass
  $new_services = array();
  foreach ( $services as $key => $service ) {
    if ( $service->ShippingService == 'USPSFirstClass' ) continue;
    $new_services[] = $service;
  }

  return $new_services;
}

wple_process_single_variation_title

Filter the listing title when splitting variations into single listings. The example below adds attribute name and attribute value. By default, only the attribute values are added. Available since version 2.0.9.9.

Usage

// customize title for single split variations (include attribute label)
function wple_process_single_variation_title( $title, $listing, $variation ) {

 $attributes = $variation['variation_attributes'];
 if ( ! is_array( $attributes ) ) return $title;

 $title = trim( $listing['auction_title'] );
 foreach ( $attributes as $attribute_name => $attribute_value ) {
 $title .= ' - ' . $attribute_name . ' ' . $attribute_value;
 }

 return $title;
}
add_filter( 'wple_process_single_variation_title', 'wple_process_single_variation_title', 10, 3 );

wple_gallery_iframe_attributes

Filter HTML attributes for the iframe tag used by gallery widgets. Available since version 2.0.9.9.

Usage

// set gallery widget iframe height to 200px
function my_custom_gallery_iframe_attributes( $iframe_attributes_array, $listing_id, $type ) {
    $iframe_attributes_array['style'] = 'height:200px; width:100%; border:none;';
    return $iframe_attributes_array;
}
add_filter( 'wple_gallery_iframe_attributes', 'my_custom_gallery_iframe_attributes', 10, 3 );

wple_complete_sale_on_ebay

Mark a specific order as shipped on eBay and optionally send tracking details and seller feedback. Available since version 2.0.9.

Usage

// mark order as shipped on eBay
$args = array();
$args['TrackingNumber']  = '123456789';
$args['TrackingCarrier'] = 'UPS';
$args['ShippedTime']     = '2016-01-01';     // optional
$args['FeedbackText']    = 'Thank You...';   // optional
do_action( 'wple_complete_sale_on_ebay', $order_id, $args );

wple_get_listings_where

This is not a WP hook but a publicly available PHP function to query the listings table. It can be useful in your custom PHP code when you need to get one or all listings for a particular status, SKU, or any other column of the wp_ebay_auctions table.

Usage

$items = wple_get_listings_where( $column, $value );

Example #1 – Get all items with a status of “changed”

$items = wple_get_listings_where( 'status', 'changed' );
foreach ($items as $item) {
  echo $item->ebay_id;
}

Example #2 – Get Item ID for a single SKU

$items = wple_get_listings_where( 'sku', 'SKU123' );
$ebay_id = $item ? $item[0]->ebay_id : null;