Skip to main content

MerchantAd

Updated

This endpoint was deprecated on June 7, 2022.  We plan to release similar functionality in the future.

 

Access:

Merchant authentication required, secure connections (https://) only.
Frequency limitation(s): 1000 request(s) per day.

Description:

This module provides the ability to create or modify any Merchant advertisement, e.g. banner images, text campaigns, and HTML ads. 

 
When making a request to this module please be aware that even if you do not specify a value for the "ad_id" parameter, you may be modifying existing advertisements. The default behavior of the module in such cases is to compare the specified "ad_title" value with your existing Merchant ads. If there is one and only one match, then that existing ad will be modified (i.e. updated). If there are zero matches then a new ad will be created, while if there are multiple matches, an error will be returned.
 
A successful API request to this module will result in two pieces of information: a status message ("Success") and a numeric id of the advertisement that was created or modified. For example, the following responses:

output=csv: Success,1234
output=tab: Success	1234
output=xml: <response><status>Success</status><ad_id>1234</ad_id></response>

would each indicate that advertisement #1234 was successfully modified.

Example usage (in PHP with the curl library):

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://www.classic.avantlink.com/api.php');
curl_setopt($ch, CURLOPT_VERBOSE, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);		
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);

// Build the details about the link you want to create/modify
$arrRequest = array();
$arrRequest['module'] = 'MerchantAd';
$arrRequest['merchant_id'] = 0; // *** Insert your Merchant id here ***
$arrRequest['auth_key'] = ''; // *** Insert your authentication key here ***
$arrRequest['ad_title'] = 'Your ad title';
$arrRequest['ad_type'] = 'image';
$arrRequest['ad_image'] = '@path_to_your_image_file';
$arrRequest['ad_destination_url'] = 'Your destination url';
$arrRequest['output'] = 'tab';
curl_setopt($ch, CURLOPT_POSTFIELDS, $arrRequest);

// Make the actual request
$strResponse = curl_exec($ch);

// Did the request work or did we receive an error?
if ($strResponse === false || curl_errno($ch) > 0) {
	echo "Error making API request; error = " . curl_errno($ch) . ', ' . curl_error($ch) . "\n";
}
else {
	// Check the API response to make sure it worked
	if (substr($strResponse, 0, 7) == 'Success') {
		$arrResponseParts = explode("\t", $strResponse);
		echo "API request was successful; ad_id = " . $arrResponseParts[1] . "\n";
	}
	else {
		echo "API request failed.\n" . $strResponse . "\n";
	}
}

// Clean up
@curl_close($ch);

 

Supported Output Formats:

  • csv
  • tab
  • xml

Parameters:

  • ad_title
    • Type: string
    • Required: true
    • Description: The title to use for this advertisement.
  • ad_type
    • Type: string
    • Required: true
    • Description: The type of ad to create or modify; valid values are: "flash", "html", "image", "text", or "video".
  • auth_key
    • Type: string
    • Required: true
    • Description: The AvantLink assigned authentication key for a particular affiliate or merchant. This is a randomly generated, 32-character, mixed alphanumeric string.
  • merchant_id
    • Type: integer
    • Required: true
    • Description: An AvantLink assigned Merchant identifier.
  • module
    • Type: string
    • Required: true
    • Description: For this module, specify "MerchantAd".
  • ad_coupon_code
    • Type: string
    • Required: false
    • Description: The coupon code to be used for the ad.
  • ad_data
    • Type: string
    • Required: false
    • Description: For html ads, this is the full HTML to use. For text ads this is the text contents. For video ads, this is the URL information used to stream the video itself. Leave empty for flash and image ads.
  • ad_destination_url
    • Type: string
    • Required: false
    • Description: For flash, image, text and video ads, this is the destination URL that users will be redirected to.
  • ad_dynamic_xml
    • Type: string
    • Required: false
    • Description: For video ads, this is an XML definition of recommendations (images and links) to be shown at the end of a video.
  • ad_end_date
    • Type: date
    • Required: false
    • Description: The ending date for this ad; after this date the ad will not be available. Defaults to today.
  • ad_exclusivity
    • Type: integer
    • Required: false
    • Description: If the ad should be restricted to a specific affiliate, then supply the appropriate affiliate id here.
  • ad_force_dynamic
    • Type: boolean
    • Required: false
    • Description: Whether or not an html ad should allow for static html affiliate integrations. 0 allows both HTML and JavaScript affiliate integrations, 1 restricts to JavaScript only. If your html ad campaign is going to change frequently or you would rather not allow the Affiliate to change the html in the ad you may want to set this value to 1. If your html ad will not be updated frequently and you don't mind the affiliate having the ability to modify the ad to fit their site you can leave this parameter off your API request or set it to 0. This boolean is only used for html ad campaigns.
  • ad_id
    • Type: integer
    • Required: false
    • Description: This value can be specified to modify a specific, pre-existing, advertisement. A value of -1 here will force a new ad to be created.
  • ad_image
    • Type: file
    • Required: false
    • Description: For image ads this will be the uploaded image; for video ads this will be the uploaded video file; for flash ads this will be the uploaded Flash file.
  • ad_image_alternate
    • Type: file
    • Required: false
    • Description: For flash ads this will be an image to use for browsers that do not have Flash enabled. Leave empty for all other ad types.
  • ad_is_coupon
    • Type: boolean
    • Required: false
    • Description: Whether or not the ad should be considered a coupon.
  • ad_keywords
    • Type: string
    • Required: false
    • Description: A comma-delimited string of keywords to use for representing this ad.
  • ad_start_date
    • Type: date
    • Required: false
    • Description: The beginning date for this ad; prior to this date the ad will not be available. Defaults to today.
  • custom_id
    • Type: string
    • Required: false
    • Description: If you have a unique internal id that you would like to associate with the ad, you can specify that here. Remember that this must be a unique value, and any duplicate non-zero id will update the existing ad.
  • output
    • Type: string
    • Required: false
    • Description: The specific output format you wish to receive results in. Possible values include: csv (comma-separated text), html, js (javascript document.write statements), rss, tab (tab-delimited text), and xml (the default). Individual modules may not support all output methods.
  • show_ad_in_feeds
    • Type: boolean
    • Required: false
    • Description: Whether or not the ad should be included in coupon data feeds.

Related articles