API DOCUMENTATION Last Update: Apr 2022

Update Existing Campaign

Updates an existing campaign's basic settings.


The data to be submitted to the API is composed of the following fields:


Fields common to all campaign types:

  field   Example   Note
user_id john1970 Required
user_password 1959caadac9b13dcb3 Required
type campaign_update Required
action campaign Required
account_id greatwidgets Required
campaign_id 1234567890123456 Required
new_campaign_name New MyRewards Optional
description You can check-in at 3rd and 5th. Optional
Output Format:
output JSON or XML Optional. If not provided, defaults to XML
callback someFunctionName Optional: JSONP format
condensed yes Optional (No white space)
Applies only to JSON(P) output



  • The ability to update campaign definitions is based on the permissions of the user_id that is making the call.
  • Only one campaign can be updated at a time. Loop this call in your program to update multiple campaigns at one time.
  • Campaign_ids cannot be changed. They are used for identification of the campaign by/to the API and are not meant for public display.
  • The new_campaign_name is the display name of the campaign, not its campaign_id. Older campaigns IDs prior to 2006 were identical to their name, but the two are still separate.


Additional Fields for Points-Based Campaigns:

  field   Example   Note
new_points_ratio 100 Optional (See Note)
new_reward_ratio 18 Optional (See Note)


  • The new_points_ratio is used to convert the amount of the purchase entered to points. If the new_points_ratio is not given or is blank, the existing value will not be changed.
  • The new_reward_ratio is also know as the spend-to-reward ratio, and is used to reverse-assign a value to the points accumulated. Setting it to a blank value turns off the abilty to redeem points by their currency value. Do not provide the "reward_ratio" parameter unless you provide a different value to change it to, or mean to leave it blank so as to turn off the abilty to redeem points by their currency value.


Additional Fields for Earn-per-Event Campaigns:

  field   Example   Note
new_amount_per_event 5.95 Optional (See Note)


  • The new_amount_per_event is a currency amount that will be added to the customer's balance for each event.
  • If the new_amount_per_event parameter is provided but without a value it will default to 0 (zero).
  • If the new_amount_per_event parameter is not provided in the request, its current value will not change.


Optional Fields for Coalition and Two-Tier Campaigns:

  field   Example   Note
coalition_opt_out Y Optional or don't include
two_tier_opt_out Y Optional or don't include


  • These are parameters that only apply for those campaigns that belong to a coalition or two-tier account. Include the parameters if the campaigns are to not belong to the coaltion or two-tier program. Otherwise, don't include them, and they will automatically belong.
  • These can be applied (status changed) on Coalition accounts only before any transactions are recorded in that campaign. After transactions begin to be recorded, any opt-out / in requests are ignored. This is to maintain the integrity of customer balances which would be affected if a campaign (merchant) is removed or added to the coalition.



Example PHP Requests:

If you are using PHP, the $data array would look like this:

For a Giftcard, Events, or BuyX Campaign:

  1. $data['user_id'] = 'john1970';
  2. $data['user_password'] = '1959caadac9b13dcb3';
  3. $data['type'] = 'campaign_update';
  4. $data['action'] = 'campaign';
  5. $data['campaign_id'] = '1234567890123450';
  6. $data['new_campaign_name'] = 'New Widget Card Name';
  7. $data['description'] = 'New Campaign Description Here';


For a Points Campaign:

  1. $data['user_id'] = 'john1970';
  2. $data['user_password'] = '1959caadac9b13dcb3';
  3. $data['type'] = 'campaign_update';
  4. $data['action'] = 'campaign';
  5. $data['campaign_id'] = '1234567890123451';
  6. $data['new_campaign_name'] = 'New Widget Rewards Name';
  7. $data['description'] = 'New Campaign Description Here';
  8. $data['new_points_ratio'] = '100';
  9. $data['new_reward_ratio'] = '18';


For a Earned-per-Event Campaign:

  1. $data['user_id'] = 'john1970';
  2. $data['user_password'] = '1959caadac9b13dcb3';
  3. $data['type'] = 'campaign_update';
  4. $data['action'] = 'campaign';
  5. $data['campaign_id'] = '1234567890123453';
  6. $data['new_campaign_name'] = 'New Widget VIP Name';
  7. $data['description'] = 'New Campaign Description Here';
  8. $data['new_amount_per_event'] = '5.95';



Success XML Response:

  1. <response status="updated">
  2. <campaign>
  3. <id>1234567890123450</id>
  4. </campaign>
  5. </response>


Error XML Response:

  1. <response status="error">
  2. <error>Error message</error>
  3. </response>