API method: update_item

This method updates an existing item. Changes are reflected immediately in all copies of your store. Any values you submit will overwrite the current value for the item, while any values you do not submit will remain unchanged.

Request Method	API Endpoint URL
POST	http://www.toldya.com/api/

Required Parameters

Parameter	Data Type	Length	Notes
action	string		update_item
api_key	string		Your API key
id	number	max 8	The id of the item you wish to update. To retrieve a listing of your items including their ids, please see view_items

Optional Parameters

Parameter	Data Type	Length	Notes
item_type_id*	number	1	The type of item you are selling: 1 = new or used product 2 = personal or professional service 3 = tickets to an event
title*	string	max 100
description*	string	max 5000
price*	number	max 9999
product_condition**	string	max 10	Must be one of the following: new, mint, excellent, good, fair, poor
service_duration_hours***	decimal	max 2	The number of hours this service will be performed, e.g. 2.5.
service_vendor_name***	string	max 100	Name or description of the person or group who will perform the service.
service_location***	string	max 1000	The location where this service will be performed. If the service will be performed at the buyer's residence, set the value = buyer's residence. If the service will be performed at your home or business, enter the complete address and optionally, directions.
start_time****	timestamp	max 12	For events, the Unix timestamp of the date and time the event begins.
end_time****	timestamp	max 12	For events, the Unix timestamp of the date and time the event ends.
qty_available	number	max 9999	The quantity of this item available for immediate sale. If not specified, defaults to 1.
category	string	max 100
url_image1	URL	max 100	Full URL of image to use as the main photo. Example: http://www.mysite.com/photo1.jpg The image will be automatically downloaded, scaled, and stored at toldya.com.
url_image2	URL	max 100	optional additional image
url_image3	URL	max 100	optional additional image
url_image4	URL	max 100	optional additional image
condition_comment	string	max 1000	For products, a short description of the condition of the product, such as minor nicks and scratches.
url	string	max 100	URL to additional information about this item. Not currently used by ToldYa.
notes	string	max 1000	Optional user data. Not used by ToldYa.

* this value can be changed, but must be present, regardless of the item_type_id
** this value can be changed, but must be set if the item_type_id = 1 (products)
*** this value can be changed, but must be set if the item_type_id = 2 (services)
**** this value can be changed, but must be set if the item_type_id = 3 (events)

Example Request

The following example demonstrates updating an item via the API. In this example, we use cURL and PHP to generate a POST request to the API and to parse the XML response. The primary purpose of creating a POST using server side code instead of simply submitting a form directly to the API is to protect your API key from unauthorized access and to allow you to process the result in a meaningful way. For more information on manually POSTing data, please see your preferred language's documentation.

/**
 * Prepare the changes for the existing item.
 * In this test, we're just updating the description,
 * price and 2 images.
 */
$post = array(
	'action'				=> 'update_item',
	'api_key' 				=> 'your api key',
	'id'					=> 1234,
	'description' 			=> 'Look your best this fall!',
	'price' 				=> '19.99',
	'url_image1'			=> 'http://somesite.com/some_photo.jpg',
	'url_image2'			=> 'http://www.othersite.com/image.gif'
);

/*
 * Use cURL to POST the data to the API and
 * retrieve the XML response.
 */
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.toldya.com/api/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);

$response = curl_exec($ch);

/**
 * handle any cURL errors
 */
if (curl_errno($ch)) {
	$message ='cURL Error #' . curl_errno($ch) . ': ' . curl_error($ch);
	die($message);
}

curl_close($ch);

/**
 * convert the XML returned by the API
 * into a simple object via this PHP method
 */
$sxml = simplexml_load_string($response);

/**
 * if successful, the API will return the 
 * new item as XML in a node called 'result'
 */
if($sxml->status == 'SUCCESS') {
	echo "Updated item: " . htmlentity_decode($sxml->result->title);
	
/**
 * if the API returns an error, handle it
 */
} else {
	$error_message = $sxml->message;
}

Example Response

Upon successful updating of your item, the API returns a success message and the data for the updated item. Here's an example of how the API responds to the update_item request above. Notice that because we did NOT submit new values for fields such as title, item_type_id or product_condition, these values remain unchanged from their original values.

<toldyaapiresponse>
    <url>https://www.toldya.com/api/</url>
    <status>SUCCESS</status>
    <message>Item #1234 successfully updated.</message>
    <result>
        <id>1234</id>
        <start_string/>
        <end_string/>
        <qty_available>1</qty_available>
        <weight>1.3</weight>
        <length>12</length>
        <width>9</width>
        <height>4.25</height>
        <title>Mens Long Sleeve Tee, Large</title>
        <description>Look your best this fall!</description>
        <price>19.99</price>
        <url/>
        <category>apparel</category>
        <product_condition>Used - Excellent</product_condition>
        <condition_comment>Tried on a few times only.</condition_comment>
        <url_image1>http://www.toldya.com/resources/images/_products/p_23desfg.jpg</url_image1>
        <url_image2>http://www.toldya.com/resources/images/_products/p_ewsg54d.gif</url_image2>
        <url_image3/>
        <url_image4/>
        <item_type_id>1</item_type_id>
        <service_duration_hours/>
        <service_vendor_name/>
        <service_location/>
    </result>
</toldyaapiresponse>