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://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>

 


back to top