Description
This API method may be used by a marketer or ecommerce system to update the status details of a coupon. At present, functionality is limited to updating the redemption status and date for specified coupons, with the ability to update other data such as expiration status planned for a future version.
A Bank ID and at least one coupon code must be specified to use this method. Individual coupons specified in the call are updated with redemption data (assuming no duplicates, missing data, etc.)
Arguments
| Field | Description | Field Type | Required | Example |
|---|---|---|---|---|
| bank_id | The identification number of the coupon bank | number | Yes | 19 |
| coupon_code | An individual coupon code | string | Yes (at least one code must be included) | M746209500 |
| redeemed | Boolean value where 1 = coupon is redeemed | boolean | No | 1 |
| redeem_date | Date when coupon is redeemed | date | No | 2016-11-17 |
| notification_email | An email address for notification when coupon update is complete | string | No | name@example.com |
| data_url | The URL of the data source located on the Internet. Allowable file extensions are .txt, .csv or .zip | string | Conditional, used if a bulk file is used for update | https://www.example.com/couponCodes.zip |
| ftp_server | IP address or host name of your FTP server | string | Conditional, required if file transfer is via FTP | ftp.mysite.com |
| ftp_user_pass | The end date for a range to limit results. | string | Conditional, required if file transfer is via FTP | 2016-10-17 |
| filename | The end date for a range to limit results. | string | Conditional, required if file transfer is via FTP | datafile.txt or /path/to_file/datafile.txt |
| compression | Only include this element if the data file is compressed. Valid compression types are:
|
string | No | .zip |
| sftp | Indicator of whether connection is via the sFTP protocol where:
NOTE: If both 1 and 1 are included in the XML payload, then the connection will be via sFTP protocol. If the sftp port is something other than 22, the port number should be specified in the ftp_server parameter preceded with a colon (e.g sftp.myftpserver.com:2222) |
boolean | No | 1 |
| ftp_ssl | Indicator of whether FTP with a valid SSL certificate should be applied where:
|
boolean | No | 1 |
| ftp_server | The end date for a range to limit results. | boolean | No | 1 |
Response
| Field | Description | Example |
|---|---|---|
| responseCode | A code indicating either success or failure of the operation. | 202 |
| responseText | Human readable description of the response code | Specified coupon bank updated |
| bank_id | The identification number of the coupon bank | 19 |
| coupon_code | An individual coupon code | ASDF1234GHJK5678 |
| updated | The number of coupon codes submitted that were successfully updated in the specified coupon bank | 17842 |
| failed | The number of coupon codes submitted that failed to be updated in the specified coupon bank. This error will typically be returned when a submitted coupon code does not match a code in the coupon bank. This count will also include any general database insert errors for any given coupon code. | 2158 |
| total | The total number of coupon codes submitted in the call. | 20000 |
| task_id | Use the value returned in this XML element as one of the input parameters for the utilities.getTasks method call in order to retrieve the current status of the bulk update job | 92794 |
Response Codes
| Response Code | Response Text | Description |
|---|---|---|
| 210 | coupon code data successfully updated | Successful update of submitted coupon code data |
| 428 | Missing variables | Required data was missing from the POSTed XML. The element will include the name of the missing required element. |
| 477 | redeem_date must be in YYYY-MM-DD format | Invalid data format provided in the input: redemption date |
| 644 | Action not taken, invalid compression | The element specified an invalid compression type or the one used on the data file does not match the one specified. |
| 646 | Action not taken, cannot pass both data_url and ftp_server | Both elements were included in the parameters. To eliminate ambiguity, the parameters need to include one or the other. |
| 647 | Action not taken, FTP user name and password is required | FTP is the specified transfer protocol and the user name and/or password is missing. |
| 648 | Action not taken, filename is required | FTP is the specified transfer protocol and the filename is missing. |
| 649 | Action not taken, invalid file type | The file extension of the data file is not supported. |
| 654 | Action not taken, data file was not copied | There was an error in retrieving the data file from either the web or FTP server. This error could arise for any number of reasons including invalid URL or FTP server, invalid FTP username and/or password, the host web server or FTP server are unavailable, etc. |
| 667 | Action not taken, invalid bank id | Invalid bank_id passed |
| 682 | Action not taken, no valid/unique coupon codes to update | No valid coupon codes were submitted. |
| 683 | Action not taken, coupon_code, data_url or ftp_server is required | Coupon code is always required, plus if HTTP(S) is the transfer protocol, the the fully qualified URL is missing. If FTP is the specified transfer protocol, then the host name or IP address of the FTP server is missing. |
| 685 | Action not taken, can not pass both coupon_code and ftp_server/data_url | user will encounter error when coupon_code parameter is used with ftp_server or data_url parameter |
Example Post
<methodCall>
<methodName>coupon.updateDetails</methodName>
<bank_id>600</bank_id>
<coupon_code>OFF50</coupon_codes>
<redeemed>1</redeemed>
<redeemed_date>2016-05-01</redeemed_date>
</methodCall>
Example Response
<methodResponse>
<item>
<methodName>coupon.updatedetails</methodName>
<responseCode>210</responseCode>
<responseText>coupon code data successfully updated</responseText>
<updated>1</updated>
<failed>1</failed>
<total>2</total>
<responseNum>1</responseNum>
</item>
</methodResponse>
Example Error
<methodResponse>
<item>
<methodName>coupon.updatedetails</methodName>
<responseCode>682</responseCode>
<responseText>Action not taken, no valid/unique coupon codes to update</responseText>
<updated>0</updated>
<failed>2</failed>
<total>2</total>
<responseNum>1</responseNum>
</item>
</methodResponse>