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

 


back to top