Contents x
      coupon.updateDetails
      • 3 Minutes to read
      • Print
      • Dark
        Light
      Contents

      coupon.updateDetails

      • 3 Minutes to read
      • Print
      • Dark
        Light
      Article summary

      General Information

      This API method may be used by a marketer or e-commerce 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 the 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 an update

      https://www.example.com/couponCodes.zip

      ftp_server

      IP address or hostname 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:

      • .zip

      • .gzip

      string

      No

      .zip

      sftp

      Indicator of whether the connection is via the sFTP protocol where:

      • 0 – Do not connect via sFTP (default)

      • 1 – Connect via sFTP

      NOTE: If both 1 and 1 are included in the XML payload, then the connection will be via the 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:

      • 0 – Do not apply SSL certificate (default)

      • 1 – Apply SSL certificate

      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 username and password is required

      FTP is the specified transfer protocol, and the user name and/or password is missing.

      648

      Action not taken, the 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 was not taken, and the 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 an invalid URL or FTP server, an 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

      A coupon code is always required, plus if HTTP(S) is the transfer protocol, the fully qualified URL is missing. If FTP is the specified transfer protocol, then the hostname 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>

      Was this article helpful?
      What's Next