WP-Lister for eBay API – Hooks and Filters

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.

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 );

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' ) 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.

wplister_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( 'wplister_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( 'wplister_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( 'wplister_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;
}	

wplister_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( 'wplister_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( 'wplister_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( 'wplister_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( 'wplister_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( 'wplister_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( 'wplister_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( 'wplister_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( 'wplister_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;
}

wplister_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( "wplister_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;
}

wplister_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( "wplister_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;
}

wplister_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( "wplister_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;
}

wplister_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( "wplister_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;
}

wplister_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( "wplister_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;
}

wplister_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. 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!

Usage

add_action( 'wplister_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', '' );
}

wplister_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( "wplister_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 );