API method: add_item

This method allows you to add a new item to your store. The newly added item will be available for immediate sale and will automatically appear in all copies of your store.

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

Required Parameters

Parameter	Data Type	Length	Notes
action	string		add_item
api_key	string		Your API key
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
Required if item_type_id = 1 (products):
product_condition	string	max 10	Must be one of the following: new, mint, excellent, good, fair, poor
Required if item_type_id = 2 (services):
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.
Required if item_type_id = 3 (events):
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.

Optional Parameters

Parameter	Data Type	Length	Notes
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.

Example Request

The following example shows how to generate a new ToldYa user 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 new Item.
 */
$post = array(
	'action'				=> 'add_item',
	'api_key' 				=> 'your api key',
	'item_type_id' 			=> '1', //new or used product
	'title' 				=> 'Mens Long Sleeve Tee, Large',
	'description' 			=> 'Look your best this summer.',
	'product_condition' 	=> 'excellent',
	'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 "Created new item: " . htmlentity_decode($sxml->result->title);
	
/**
 * if the API returns an error, handle it
 */
} else {
	$error_message = $sxml->message;
}

Example Response

Here's an example of how the API responds to creating the new item above. Notice that the images submitted in url_image1 and url_image2 have been copied to toldya.com and that the product_condition column has been reformatted.

<toldyaapiresponse>
    <url>https://www.toldya.com/api/</url>
    <status>SUCCESS</status>
    <message>Item successfully added.</message>
    <result>
        <id>1234</id>
        <start_string/>
        <end_string/>
        <qty_available>1</qty_available>
        <weight/>
        <length/>
        <width/>
        <height/>
        <title>Mens Long Sleeve Tee, Large</title>
        <description>Look your best this fall in this stylish black long sleeve tee.</description>
        <price>19.99</price>
        <url/>
        <category/>
        <product_condition>Used - Excellent</product_condition>
        <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>