Create New Campaign

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

Notes:

• The ability to create new campaigns is based on the permissions of the user_id that is making the call.
• Only one campaign can be created at a time. Loop this call in your program to create multiple campaigns at one time.
• The latitude and longitude parameters can be used in order to create a geo-fenced campaign. They are completely optional.

Additional Fields for Points-Based Campaigns:

Notes:

• The points_ratio is required in so far as for any amount entered, there has to be a ratio to convert it to points. If for some reason the points_ratio is not given or is blank, it will default to 100:1 (ie: $1.00 = 100 points, so that cents can be captured.)
• The reward_ratio is also know as the spend-to-reward ratio, and is used to reverse-assign a value to the points accumulated. It is optional since not setting it (or setting it to a blank or null value) turns off the abilty to redeem points by their currency value. (This is the default state.) Hence it needs to be set only if this is an ability you want this campaign to provide.

Additional Fields for Earn-per-Event Campaigns:

Notes:

• The amount_per_event is a currency amount that will be added to the customer's balance for each event. If not provided or missing, it will default to 0 (zero).

Optional Fields for Coalition and Two-Tier Campaigns:

Notes:

• 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.

Example PHP Requests:

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

For Giftcard, Events, or BuyX Campaigns:

              $data['user_id'] = 'john1970';
              $data['user_password'] = '1959caadac9b13dcb3'; 
              $data['type'] = 'campaign_new';
              $data['action'] = 'campaign';
              $data['campaign_name'] = 'Widget Card';
              $data['campaign_type'] = 'giftcard';
              or
              $data['campaign_type'] = 'events';
              or
              $data['campaign_type'] = 'buyx';
          

For a Points Campaign:

              $data['user_id'] = 'john1970';
              $data['user_password'] = '1959caadac9b13dcb3'; 
              $data['type'] = 'campaign_new';
              $data['action'] = 'campaign';
              $data['campaign_type'] = 'points';
              $data['campaign_name'] = 'Widget Rewards';
              $data['points_ratio'] = '50';
              $data['reward_ratio'] = '15';
          

For a Earned-per-Event Campaign:

              $data['user_id'] = 'john1970';
              $data['user_password'] = '1959caadac9b13dcb3'; 
              $data['type'] = 'campaign_new';
              $data['action'] = 'campaign';
              $data['campaign_type'] = 'earned';
              $data['campaign_name'] = 'Widget VIP';
              $data['amount_per_event'] = '4.95';
          

Success XML Response:

              <response status="success">
                  <campaign>
                    <id>1234567890123456</id>
                  </campaign>
              </response>
          

Error XML Response:

              <response status="error">
                  <error>Error message</error>
              </response>
          

Create New Campaign Reward

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

Notes:

• The ability to create rewards is based on the permissions of the user_id that is making the call.
• Only one reward can be added at a time. Loop this call in your program to add multiple rewards at the same time.
• This call applies only to Points and Event-Based campaigns.
• The reward_level is an amount that is depedent on the campaign type. For example:
  • For Points-based campaigns: 1000 points = Free Widget
  • For Event-based campaigns: 15 events = Free Widget
• The reward_identifier is an optional field that lets you specify a reward id such as a SKU, used mostly for 3rd party fullfilment integrations. Please note that when identifying the reward to the API, you MUST use the <id> that is returned in the XML construct, NOT the <reward_id> which corresponds to this optional reward_identifier field.

Example PHP Request:

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

              $data['user_id'] = 'john1970';
              $data['user_password'] = '1959caadac9b13dcb3'; 
              $data['type'] = 'campaign_new';
              $data['action'] = 'reward';
              $data['account_id'] = 'greatwidgets';
              $data['campaign_id'] = '1234567890123456';
              $data['reward_level'] = '1000';
              $data['reward_description'] = 'Free Widget';
              $data['reward_identifier'] = '1010101';
          

Success XML Response:

              <response status="success">
                  <campaign>
                      <reward>
                        <id>14</id>
                      </reward>
                  </campaign>
              </response>
          

Note:

• A successful result will return the reward_id of the reward. This id can also be retrieved with the Campaign - List Rewards API call.

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>
          

Create New Campaign Promotion

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

Notes:

• The ability to create promotions is based on the permissions of the user_id that is making the call.
• The promo_amount is based on the promo_operation chosen:
  • The "x" operation is a multiplier, so the promo_amount given will multiply the amount of points earned. For example:
    • A value of "1.25" is equivalent to adding 25% more points (100pts becomes 125pts)
    • A value of "0.5" is quivlaent to having the amount of points earned (100pts becomes 50pts)
  • The "+" operation adds the promo_amount to the points earned. For example:
    • A value of "100" will add 100 points to the amount of points earned.
    • A value of "-50" will subtract 50 points from the amount of points earned.
• The promo_description is required in order to properly show some decriptive text in lists of promotions.
• Only one promotion can be added at a time. Loop this call in your program to add multiple promotions at the same time.

Example PHP Request:

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

              $data['user_id'] = 'john1970';
              $data['user_password'] = '1959caadac9b13dcb3'; 
              $data['type'] = 'campaign_new';
              $data['action'] = 'promo';
              $data['account_id'] = 'greatwidgets';
              $data['campaign_id'] = '1234567890123456';
              $data['promo_operation'] = 'x';
              $data['promo_amount'] = '1.25';
              $data['promo_description'] = 'Pre-booking bonus (25%)';
          

Success XML Response:

              <response status="success">
                  <campaign>
                      <promo>
                        <id>14</id>
                      </promo>
                      </campaign>
              </response>
          

Note:

• A successful result will return the promo_id of the promotion. This id can also be retrieved with the Campaign - List Promotions API call.

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>
          

Create New BuyX Campaign Item

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

Notes:

• The ability to create items is based on the permissions of the user_id that is making the call.
• Only one item can be added at a time. Loop this call in your program to add multiple items at the same time.
• This call applies only to Buy X Get 1 Free campaigns.
• The reward_level is the quantity of items that need to be purchased before the next one is free.
• The item_identifier is an optional field that lets you specify an item ID such as a SKU.

Example PHP Request:

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

              $data['user_id'] = 'john1970';
              $data['user_password'] = '1959caadac9b13dcb3'; 
              $data['type'] = 'campaign_new';
              $data['action'] = 'item';
              $data['account_id'] = 'greatwidgets';
              $data['campaign_id'] = '1234567890123456';
              $data['reward_level'] = '10';
              $data['item_description'] = 'Coffee or Tea';
              $data['item_identifier'] = '1DF345S1';
          

Success XML Response:

              <response status="success">
                  <campaign>
                      <item>
                        <id>14</id>
                      </item>
                  </campaign>
              </response>
          

Note:

• A successful result will return the item_id of the item. This id can also be retrieved with the Campaign - List BuyX Items API call.

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>
          

Create New Campaign Depreciation

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

Notes:

• The ability to add a depreciations is based on the permissions of the user_id that is making the call.
• Only one depreciation can be added at a time.
  • Depreciations can only be created for Points and GiftCard (stored value) type of campaigns.
  • The depreciation_type determines how the depreciation is calculated. If set to "last_transaction", depreciation will not be calculated until the last transaction recorded matches one of the intervals specified (ex: airline points that expire only if you stop earning or redeeming them for a certain amount of time.) If it is set to "per_transaction" then the depreciation schedule starts being applied from the date that each transaction is recorded for that transaction. (ex: points that expire after a certain amount of time, even if you use the card in the meantime -- essentially making the customer redeem their points as soon as possible or lose them.)
  • The depreciation_interval and depreciation_interval_type specify the amount of time until points earned or stored value balance depreciate. For example "18" + "months" means that after 18 months the depreciation will apply. Or to put another way, when looking at a list of transactions, those that are over 18 months old will have the depreciation applied to them when calculating the current balance.
  • The depreciation_percentage specify the percentage by which the points or stored value amount will be reduced. For example, specifying "100" means that after the depreciation interval, 100% of the earned points in an affected transaction will be depreciated (in this case, leaving the user with a balance of 0 points. Specifying two depreciations, for example, one for 25% after 1 year and another for 50% after 2 years, means that after 1 year the original amount will be depreciated by 25% (so for example, 100 points will now be worth only 75 points) and after two years, the original amount -- not the already depreciated amount -- will be depreciated by 50% (ex: the 100 points which were previously depreciated to 75 points will now be worth 50 points.)
  • IMPORTANT: Please note that because a customer's transaction history will likely have redemptions of rewards mixed in with earnings of points, or stored value reductions (payments) mixed in with (re)loadings, the calculation of the current balance can get pretty complicated: Redemptions and payments are based on the balance at the time of redemption or payment and thus the amount of points needed to redeem, or stored value needed to pay, are taken from the pool of available points or stored value on a first-earned/loaded-first-used basis, NOT a first-earned/loaded-last-used basis. Once those points are used for a redemption, or stored value used for a payment, they are no longer depreciated, only the remaining available points (or stored value amount) are depreciated.

Example PHP Request:

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

              $data['user_id'] = 'john1970';
              $data['user_password'] = '1959caadac9b13dcb3'; 
              $data['type'] = 'depreciation_new';
              $data['account_id'] = 'greatwidgets';
              $data['campaign_id'] = '1234567890123456';
              $data['depreciation_type'] = 'last_transaction';
              $data['depreciation_interval'] = '18';
              $data['depreciation_interval_type'] = 'months';
              $data['depreciation_percentage'] = '100';
          

Success XML Response:

              <response status="success">
                  <depreciation status="new">
                      <id>543</id>
                      <type>last_transaction</type>
                      <interval>18</interval>
                      <interval_type>months</interval_type>
                      <percentage>100</percentage>
                  </depreciation>
              </response>
          

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>
          

Create New Campaign Fee

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

Notes:

• The ability to add a fee is based on the permissions of the user_id that is making the call.
• Only one fee can be added at a time.
  • Fees can only be created for Points and GiftCard (stored value) type of campaigns.
  • The fee_interval and interval_type specify the amount of time until the fee will be applied. For example "18" + "months" means that after 18 months the fee will apply.

Example PHP Request:

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

              $data['user_id'] = 'john1970';
              $data['user_password'] = '1959caadac9b13dcb3'; 
              $data['type'] = 'campaign_fee_new';
              $data['account_id'] = 'greatwidgets';
              $data['campaign_id'] = '1234567890123456';
              $data['fee_interval'] = '18';
              $data['interval_type'] = 'months';
              $data['fee_amount'] = '100';
              $data['fee_description'] = 'Service Charge';
          

Success XML Response:

              <response status="success">
                  <fee status="new">
                      <id>453</id>
                      <interval>18</interval>
                      <interval_type>months</interval_type>
                      <amount>100</amount>
                      <description>100</description>
                  </fee>
              </response>
          

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>
          

Update Existing Campaign

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

Notes:

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

Notes:

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

Notes:

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

Notes:

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

              $data['user_id'] = 'john1970';
              $data['user_password'] = '1959caadac9b13dcb3'; 
              $data['type'] = 'campaign_update';
              $data['action'] = 'campaign';
              $data['campaign_id'] = '1234567890123450';
              $data['new_campaign_name'] = 'New Widget Card Name';
          

For a Points Campaign:

              $data['user_id'] = 'john1970';
              $data['user_password'] = '1959caadac9b13dcb3'; 
              $data['type'] = 'campaign_update';
              $data['action'] = 'campaign';
              $data['campaign_id'] = '1234567890123451';
              $data['new_campaign_name'] = 'New Widget Rewards Name';
              $data['new_points_ratio'] = '100';
              $data['new_reward_ratio'] = '18';
          

For a Earned-per-Event Campaign:

              $data['user_id'] = 'john1970';
              $data['user_password'] = '1959caadac9b13dcb3'; 
              $data['type'] = 'campaign_update';
              $data['action'] = 'campaign';
              $data['campaign_id'] = '1234567890123453';
              $data['new_campaign_name'] = 'New Widget VIP Name';
              $data['new_amount_per_event'] = '5.95';
          

Success XML Response:

              <response status="updated">
                  <campaign>
                    <id>1234567890123450</id>
                  </campaign>
              </response>
          

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>
          

Update Existing Campaign Reward

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

Notes:

• The ability to update rewards is based on the permissions of the user_id that is making the call.
• Only one reward can be updated at a time. Loop this call in your program to update multiple rewards at the same time.
• This call applies only to Points and Event-Based campaigns.
• The new_reward_level is an amount that is depedent on the campaign type. For example:
  • For Points-based campaigns: 1000 points = Free Widget
  • For Event-based campaigns: 15 events = Free Widget
• The new_reward_identifier is an optional field that lets you specify a reward id such as a SKU, used mostly for 3rd party fullfilment integrations. Please note that when identifying the reward to the API, you MUST use the <id> that is returned in the XML construct, NOT the <reward_id> which corresponds to this optional new_reward_identifier field.

Example PHP Request:

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

              $data['user_id'] = 'john1970';
              $data['user_password'] = '1959caadac9b13dcb3'; 
              $data['type'] = 'campaign_update';
              $data['action'] = 'reward';
              $data['account_id'] = 'greatwidgets';
              $data['campaign_id'] = '1234567890123456';
              $data['reward_id'] = '1234567890123456';
              $data['new_reward_level'] = '2000';
              $data['new_reward_description'] = 'Free Other Widget';
              $data['new_reward_identifier'] = '1010102';
          

Success XML Response:

              <response status="success">
                  <reward status="updated">
                    <id>57</id>
                  </reward>
              </response>
          

Note:

• A successful result will return the reward_id of the reward. This id can also be retrieved with the Campaign - List Rewards API call.

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>
          

Update Existing Campaign Promotion

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

Notes:

• The ability to updates promotions is based on the permissions of the user_id that is making the call.
• At least one of the three parameters needs to be given (new_promo_operation, new_promo_amount, or new_promo_description.)
• None of these three can be "blank".
• If any of the parameters does not need to be updated, do not include it in the API call.
• The new_promo_amount is based on the new_promo_operation chosen:
  • The "x" operation is a multiplier, so the new_promo_amount given will multiply the amount of points earned. For example:
    • A value of "1.25" is equivalent to adding 25% more points (100pts becomes 125pts)
    • A value of "0.5" is quivlaent to having the amount of points earned (100pts becomes 50pts)
  • The "+" operation adds the new_promo_amount to the points earned. For example:
    • A value of "100" will add 100 points to the amount of points earned.
    • A value of "-50" will subtract 50 points from the amount of points earned.
• An error will be output if the new_promo_amount is blank or 0, and the new_promo_operation is "x". This will also happen If just one is given to the API but the other is already recorded as such. This is because "x" promotions cannot be zero otherwise this would trigger some "divide by zero" errors in certain instances. If you need to use a "zero" promotion, use the "+" operator. If you need the promotion to completely wipe the points earned with the purchase, use "0.001" for example.
• Only one promotion can be updated at a time. Loop this call in your program to update multiple promotions at the same time.

Example PHP Request:

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

              $data['user_id'] = 'john1970';
              $data['user_password'] = '1959caadac9b13dcb3'; 
              $data['type'] = 'campaign_update';
              $data['action'] = 'promo';
              $data['account_id'] = 'greatwidgets';
              $data['campaign_id'] = '1234567890123456';
              $data['promo_id'] = 'greatwidgets';
              $data['new_promo_operation'] = '+';
              $data['new_promo_amount'] = '50';
              $data['new_promo_description'] = 'Pre-booking bonus (50pt)';
          

Success XML Response:

              <response status="success">
                  <promo status="updated">
                    <id>14</id>
                  </promo>
              </response>
          

Note:

• A successful result will return the promo_id of the promotion. This id can also be retrieved with the Campaign - List Promotions API call.

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>
          

Update Existing BuyX Campaign Item

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

Notes:

• The ability to update items is based on the permissions of the user_id that is making the call.
• Only one item can be updated at a time. Loop this call in your program to add multiple items at the same time.
• This call applies only to "Buy X Get 1 Free" campaigns.
• The new_reward_level is the quantity of items that need to be purchased before the next one is free.
• If changing the Item Description by providing a new_item_description this will also update all past transactions so that it will look like previous transactions were for the same newly updated item. To keep the old description just create a new item instead.
• The new_item_identifier is an optional field that lets you specify an item ID such as a SKU.

Example PHP Request:

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

              $data['user_id'] = 'john1970';
              $data['user_password'] = '1959caadac9b13dcb3'; 
              $data['type'] = 'campaign_update';
              $data['action'] = 'item';
              $data['account_id'] = 'greatwidgets';
              $data['campaign_id'] = '1234567890123456';
              $data['item_id'] = '234';
              $data['new_reward_level'] = '11';
              $data['new_item_description'] = 'Coffee or Tea';
              $data['new_item_identifier'] = '1DF345S1';
          

Success XML Response:

              <response status="success">
                  <item status="updated">
                    <id>14</id>
                  </item>
              </response>
          

Note:

• A successful result will return the item_id of the item. This id can also be retrieved with the Campaign - List BuyX Items API call.

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>
          

Update Existing Campaign Depreciation

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

Notes:

• The ability to edit existing depreciations is based on the permissions of the user_id that is making the call.
• Only one depreciation can be updated at a time.
  • Depreciations can only be created for Points and GiftCard (stored value) type of campaigns.
  • The depreciation_interval and depreciation_interval_type specify the amount of time until points earned or stored value balance depreciate. For example "18" + "months" means that after 18 months the depreciation will apply. Or to put another way, when looking at a list of transactions, those that are over 18 months old will have the depreciation applied to them when calculating the current balance.
  • The depreciation_percentage specify the percentage by which the points or stored value amount will be reduced. For example, specifying "100" means that after the depreciation interval, 100% of the earned points in an affected transaction will be depreciated (in this case, leaving the user with a balance of 0 points. Specifying two depreciations, for example, one for 25% after 1 year and another for 50% after 2 years, means that after 1 year the original amount will be depreciated by 25% (so for example, 100 points will now be worth only 75 points) and after two years, the original amount -- not the already depreciated amount -- will be depreciated by 50% (ex: the 100 points which were previously depreciated to 75 points will now be worth 50 points.)
  • IMPORTANT: Please note that because a customer's transaction history will likely have redemptions of rewards mixed in with earnings of points, or stored value reductions (payments) mixed in with (re)loadings, the calculation of the current balance can get pretty complicated: Redemptions and payments are based on the balance at the time of redemption or payment and thus the amount of points needed to redeem, or stored value needed to pay, are taken from the pool of available points or stored value on a first-earned/loaded-first-used basis, NOT a first-earned/loaded-last-used basis. Once those points are used for a redemption, or stored value used for a payment, they are no longer depreciated, only the remaining available points (or stored value amount) are depreciated.

Example PHP Request:

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

              $data['user_id'] = 'john1970';
              $data['user_password'] = '1959caadac9b13dcb3'; 
              $data['type'] = 'depreciation_update';
              $data['account_id'] = 'greatwidgets';
              $data['campaign_id'] = '1234567890123456';
              $data['depreciation_id'] = '543';
              $data['depreciation_type'] = 'last_transaction';
              $data['depreciation_interval'] = '18';
              $data['depreciation_interval_type'] = 'months';
              $data['depreciation_percentage'] = '100';
          

Success XML Response:

              <response status="success">
                  <depreciation status="updated">
                      <id>543</id>
                      <type>last_transaction</type>
                      <interval>18</interval>
                      <interval_type>months</interval_type>
                      <percentage>100</percentage>
                  </depreciation>
              </response>
          

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>
          

Update Existing Campaign Fee

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

Notes:

• The ability to update a fee is based on the permissions of the user_id that is making the call.
• Only one fee can be updated at a time.
  • Fees can only be updated (or created) for Points and GiftCard (stored value) type of campaigns.
  • The fee_interval and interval_type specify the amount of time until the fee will be applied. For example "18" + "months" means that after 18 months the fee will apply.

Example PHP Request:

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

              $data['user_id'] = 'john1970';
              $data['user_password'] = '1959caadac9b13dcb3'; 
              $data['type'] = 'campaign_fee_update';
              $data['account_id'] = 'greatwidgets';
              $data['campaign_id'] = '1234567890123456';
              $data['fee_interval'] = '18';
              $data['interval_type'] = 'months';
              $data['fee_amount'] = '100';
              $data['fee_description'] = 'Service Charge';
          

Success XML Response:

              <response status="success">
                  <fee status="updated">
                      <id>453</id>
                      <interval>18</interval>
                      <interval_type>months</interval_type>
                      <amount>100</amount>
                      <description>100</description>
                  </fee>
              </response>
          

Error XML Response:

              <response status="error">
                <error>Error message</error>
              </response>
          

Campaigns List

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

Notes:

• When using this call, the list of campaigns returned is based on the permissions of the user_id that is making the call.
• The type_restrict parameter is optional, and can be combined with the searchField. If it's not given, all campaign types are returned. If you want multiple campaign types, list each type separated by a comma, which makes it slightly different than achieving the same thing using searchField=campaign_type, which is restricted to a single campaign type.

Example PHP Request:

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

                  $data['API'] = '1.5';
                  $data['user_id'] = 'john1970';
                  $data['user_api_key'] = '1959caadac9b13dcb3'; 
                  $data['type'] = 'campaigns_list';
                  $data['account_id'] = 'greatwidgets';
              

Success XML Response:

                  <response status="success">
                      <campaign>
                          <id>1234567890123456</id>
                          <name>Widget Rewards</name>
                          <type>points</type>
                          <points_ratio>5</points_ratio>
                          <reward_ratio>15</reward_ratio>
                          <currency>EUR</currency>
                          <glyph>€</glyph>
                      </campaign>
                      <campaign>
                          <id>2345678901234567</id>
                          <name>Sales Bucks</name>
                          <type>earned</type>
                          <earned_per_event>4.95</earned_per_event>
                          <currency>EUR</currency>
                          <glyph>€</glyph>
                      </campaign>
                      <campaign>
                          <id>3456789012345678</id>
                          <name>Frequent Shopper Rewards</name>
                          <type>buyx</type>
                          <item>
                              <id>45678</id>
                              <description>Coffees and Teas</description>
                              <earn_ratio>10</earn_ratio>
                              ...
                          </item>
                      </campaign>
                      ...
                  </response>
              

Notes:
There are 5 campaign types:

• points (Points-based campaigns)
• giftcard (Currency-based campaigns)
• events (Event-based campaigns
• earned (Currency earned per event campaigns)
• buyx (Buy X Get 1 Free type campaigns)

Gift Card and events-based campaigns do not have ratios to report.

Example PHP request to list ONLY Gift Cards and Points campaigns:

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

                  $data['API'] = '1.5';
                  $data['user_id'] = 'john1970';
                  $data['user_api_key'] = '1959caadac9b13dcb3'; 
                  $data['type'] = 'campaigns_list';
                  $data['account_id'] = 'greatwidgets';
                  $data['type_restrict'] = 'giftcard, points';
              

Success XML Response:

                  <response status="success">
                      <campaign>
                          <id>2345678901234567</id>
                          <name>My Stored Value Card</name>
                          <type>giftcard</type>
                      </campaign>
                      <campaign>
                          <id>1234567890123456</id>
                          <name>Widget Rewards</name>
                          <type>points</type>
                          <points_ratio>5</points_ratio>
                          <reward_ratio>15</reward_ratio>
                      </campaign>
                      ...

                  </response>
              

Error XML Response:

                  <response status="error">
                    <error>Error message</error>
                  </response>
              

Deactivated (on hold) Campaigns List

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

Notes:

• When using this call, the list of deactivated campaigns returned is based on the permissions of the user_id that is making the call. Only manager-level users can make this call.
• The type_restrict parameter is optional, and can be combined with the searchField. If it's not given, all campaign types are returned. If you want multiple campaign types, list each type separated by a comma, which makes it slightly different than achieving the same thing using searchField=campaign_type, which is restricted to a single campaign type.

Example PHP Request:

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

                  $data['API'] = '1.5';
                  $data['user_id'] = 'john1970';
                  $data['user_api_key'] = '1959caadac9b13dcb3'; 
                  $data['type'] = 'campaigns_inactive_list';
                  $data['account_id'] = 'greatwidgets';
              

Success XML Response:

                  <response status="success">
                      <campaigns>
                          <campaign>
                              <id>1234567890123456</id>
                              <name>Widget Rewards</name>
                              <type>points</type>
                              <points_ratio>5</points_ratio>
                              <reward_ratio>15</reward_ratio>
                          </campaign>
                          <campaign>
                              <id>2345678901234567</id>
                              <name>Sales Bucks</name>
                              <type>earned</type>
                              <earned_per_event>4.95</earned_per_event>
                          </campaign>
                          <campaign>
                              <id>3456789012345678</id>
                              <name>Frequent Shopper Rewards</name>
                              <type>buyx</type>
                              <item>
                                  <id>45678</id>
                                  <description>Coffees and Teas</description>
                                  <earn_ratio>10</earn_ratio>
                                  ...
                              </item>
                          </campaign>
                          ...								</campaign>
                  </response>
              

Notes:
There are 5 campaign types:

• points (Points-based campaigns)
• giftcard (Currency-based campaigns)
• events (Event-based campaigns
• earned (Currency earned per event campaigns)
• buyx (Buy X Get 1 Free type campaigns)

Gift Card and events-based campaigns do not have ratios to report.

Example PHP request to list ONLY Gift Cards and Points deactivated campaigns:

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

                  $data['API'] = '1.5';
                  $data['user_id'] = 'john1970';
                  $data['user_api_key'] = '1959caadac9b13dcb3'; 
                  $data['type'] = 'campaigns_inactive_list';
                  $data['account_id'] = 'greatwidgets';
                  $data['type_restrict2'] = 'giftcard, points';
              

Success XML Response:

                  <response status="success">
                          <campaign>
                              <id>2345678901234567</id>
                              <name>My Stored Value Card</name>
                              <type>giftcard</type>
                          </campaign>
                          <campaign>
                              <id>1234567890123456</id>
                              <name>Widget Rewards</name>
                              <type>points</type>
                              <points_ratio>5</points_ratio>
                              <reward_ratio>15</reward_ratio>
                          </campaign>
                          ...
                      </campaign>
                  </response>
              

Error XML Response:

                  <response status="error">
                    <error>Error message</error>
                  </response>
              

Campaign Rewards List

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

Notes:

• When using this call, the 'account_id' MUST be the unique Owner ID that is found in the "Edit Account Information" page reached from the main page / control panel.
• The 'campaign_id' MUST be the unique Campaign ID that is found in the "Edit Campaign" page reached from the main page / control panel listing of campaigns.

Example PHP Request:

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

                  $data['user_id'] = 'john1970';
                  $data['user_password'] = '1959caadac9b13dcb3'; 
                  $data['type'] = 'campaign_rewards';
                  $data['account_id'] = 'greatwidgets';
                  $data['campaign_id'] = '1111222233334444';
              

Success XML Response:

                  <response status="success">
                      <campaign>
                          <id>1111222233334444</id>
                      </campaign>
                      <rewards>
                          <reward>
                              <id>356</id>
                              <level>1000</level>
                              <description>Free Widget</description>
                          </reward>
                          <reward>
                              <id>417</id>
                              <level>1500</level>
                              <description>Free Service</description>
                              <reward_id>156739948736</reward_id>
                          </reward>
                          ...
                      </rewards>
                  </response>
              

Notes:

• When identifying the reward to the API, you MUST use the <id> that is returned in the XML construct, NOT the <reward_id> which corresponds to the optional reward_identifier field.
• Rewards are only available for the following type of campaigns:
  • Points-based campaigns
  • Event-based campaigns
  • For Buy X Get 1 Free type campaigns, this will return the products/services previously defined to be able to be accumulated, and the number of times that item needs to be purchased before it should be available as a reward.

Error XML Response:

                  <response status="error">
                    <error>Error message</error>
                  </response>
              

Campaign Promotions List

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

Notes:

• When using this call, the 'account_id' MUST be the unique Owner ID that is found in the "Edit Account Information" page reached from the main page / control panel.
• The 'campaign_id' MUST be the unique Campaign ID that is found in the "Edit Campaign" page reached from the main page / control panel listing of campaigns.
• The searchField and sortField are:
  • promotion - For the text description of the promotion
  • operation - Whether the promotion is a "+" (add) or "x" (multiply) promotion.
  • multiplier - The amount the promotion adds to or multiplies the transaction amount by.

Example PHP Request:

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

                  $data['API'] = '1.5';
                  $data['user_id'] = 'john1970';
                  $data['user_api_key'] = '1959caadac9b13dcb3'; 
                  $data['account_id'] = 'greatwidgets';
                  $data['type'] = 'campaign_promos';
                  $data['campaign_id'] = '1111222233334444';
                  $data['searchField'] = 'promotion';
                  $data['searchValue'] = 'Bonus';
                  $data['searchOper'] = 'cn';
                  $data['sortField'] = 'promotion';
                  $data['sortOrder'] = 'ASC';
                  $data['offset'] = '30';
                  $data['length'] = '10';
              

Success XML Response:

                  <response status="success">
                      <campaign>
                          <id>1111222233334444</id>
                          <name>Campaign Name</name>
                      </campaign>
                      <pagination>
                          <total>56</total>
                          <offset>30</offset>
                      </pagination>
                      <promotions>
                          <promotion>
                              <id>365</id>
                              <operand>+</operand>
                              <value>1000</value>
                              <description>Sign-up Bonus</description>
                              <promo_custom_id>XFA-567</promo_custom_id>
                              <promo_start_date>2013-08-01 00:00:00</promo_start_date>
                              <promo_end_date>2013-08-31 23:59:59</promo_end_date>
                          </promotion>
                          <promotion>
                              <id>423</id>
                              <operand>x</operand>
                              <value>1.2</value>
                              <description>20% More Points Tuesdays Bonus</description>
                              <promo_custom_id>XFA-256</promo_custom_id>
                              <promo_start_date>2013-09-01 08:00:00</promo_start_date>
                              <promo_end_date>2013-09-31 23:59:59</promo_end_date>
                          </promotion>
                          ...
                      </promotions>
                  </response>
              

Notes:
Operands are either:

• "+" to add or subtract (negative value) an amount from the transaction.
• "x" to multiply the amount of the transaction by the value

No Promos XML Response:

                  <response status="none">
                    <message>Language-specific message</message>
                  </response>
              

Error XML Response:

                  <response status="error">
                    <error>Error message</error>
                  </response>
              

Campaign Depreciations List

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

Notes:

• Depreciations are only available for Points and GiftCard (Stored Value) type of campaigns.

Example PHP Request:

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

                  $data['user_id'] = 'john1970';
                  $data['user_password'] = '1959caadac9b13dcb3'; 
                  $data['type'] = 'campaign_depreciations';
                  $data['account_id'] = 'greatwidgets';
                  $data['campaign_id'] = '1234567890123456';
              

Success XML Response:

                  <response status="success">
                      <campaign>
                        <id>1111222233334444</id>
                      </campaign>
                      <depreciations>
                          <depreciation>
                              <id>356</id>
                              <depreciation_interval>18</depreciation_interval>
                              <depreciation_interval_type>months</depreciation_interval_type>
                              <depreciation_percentage>50</depreciation_percentage>
                          </depreciation>
                          <depreciation>
                              <id>417</id>
                              <depreciation_interval>4</depreciation_interval>
                              <depreciation_interval_type>years</depreciation_interval_type>
                              <depreciation_percentage>100</depreciation_percentage>
                          </depreciation>
                          ...
                      </depreciations>
                  </response>
              

Notes:

• When identifying a depreciation entry to another API call, you use the <id> that is returned in the XML construct such as the one above.

Error XML Response:

                  <response status="error">
                    <error>Error message</error>
                  </response>
              

Campaign Fees List

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

Notes:

• Campaign fees are only available for Points and GiftCard (Stored Value) type of campaigns.

Example PHP Request:

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

                  $data['user_id'] = 'john1970';
                  $data['user_password'] = '1959caadac9b13dcb3'; 
                  $data['type'] = 'campaign_fees';
                  $data['account_id'] = 'greatwidgets';
                  $data['campaign_id'] = '1234567890123456';
              

Success XML Response:

                  <response status="success">
                      <campaign>
                        <id>1111222233334444</id>
                      </campaign>
                      <fees>
                          <fee>
                              <id>463</id>
                              <interval>1</interval>
                              <interval_type>years</interval_type>
                              <amount>10</amount>
                              <description>Yearly account fee</description>
                          </fee>
                          ...
                      </fees>
                  </response>
              

Notes:

• When identifying a depreciation entry to another API call, you use the <id> that is returned in the XML construct such as the one above.
• The amount is either the amount of points or money to be deducted, depending on the campaign type.

Error XML Response:

                  <response status="error">
                    <error>Error message</error>
                  </response>
              

BuyX Campaign Items List

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

Notes:

• When using this call, the 'account_id' MUST be the unique Owner ID that is found in the "Edit Account Information" page reached from the main page / control panel.
• The 'campaign_id' MUST be the unique Campaign ID that is found in the "Edit Campaign" page reached from the main page / control panel listing of campaigns.
  • The searchField and sortField are:
    • service_product - For the text description of the items accumulated
    • reward_id - the Reward ID of the item.
    • buy_amount - The amount of times the item has to be purchased to earn a free one.

Example PHP Request:

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

                  $data['API'] = '1.5';
                  $data['user_id'] = 'john1970';
                  $data['user_api_key'] = '1959caadac9b13dcb3'; 
                  $data['type'] = 'buyx_items_list';
                  $data['account_id'] = 'greatwidgets';
                  $data['campaign_id'] = '1111222233334444';$data['searchField'] = 'service_product';
                  $data['searchValue'] = 'Coffee';
                  $data['searchOper'] = 'cn';
                  $data['sortField'] = 'service_product';
                  $data['sortOrder'] = 'ASC';
                  $data['offset'] = '30';
                  $data['length'] = '10';
              

Success XML Response:

                  <response status="success">
                      <campaign>
                          <id>1111222233334444</id>
                          <name>Store Rewards!</name>
                      </campaign>
                      <pagination>
                          <total>56</total>
                          <offset>30</offset>
                      <pagination>
                      <buyx_items>
                          <item>
                              <id>345</id>
                              <description>Coffees and Lattes</description>
                              <quantity>8</quantity>
                          </item>
                          <item>
                              <id>494</id>
                              <description>Blended Drinks</description>
                              <quantity>12</quantity>
                              <reward_id>12398749834</reward_id>
                          </item>
                          ...
                      </buyx_items>
                  </response>
              

Notes:

• The "quantity" is the amount of the item needed to be purchased before the next one is free – Not a customer's balance.
• When identifying the item (or "reward") to the API, you MUST use the <id> that is returned in the XML construct, NOT the <reward_id> which corresponds to the optional item_identifier field.

Error XML Response:

                  <response status="error">
                    <error>Error message</error>
                  </response>
              

Delete a Campaign

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

Notes:

• The ability to delete campaigns is based on the permissions of the user_id that is making the call.
• Only one campaign can be deleted at a time. Loop this call in your program to delete multiple campaigns.
• Deactivating a campaign removes it from the list of campaigns that is returned in many other calls, without deleting any data associated with it (settings, customer transactions, etc.) This is often used to "turn off" recurring seasonal campaigns.

Example PHP Request:

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

                  $data['user_id'] = 'john1970';
                  $data['user_password'] = '1959caadac9b13dcb3'; 
                  $data['type'] = 'campaign_delete';
                  $data['action'] = 'campaign';
                  $data['account_id'] = 'greatwidgets';
                  $data['campaign_id'] = '1234567890123456';
              

Success XML Response:

                  <response status="success">
                      <campaign status="deleted">
                        <id>1234567890123456</id>
                      </campaign>
                  </response>
              

Error XML Response:

                  <response status="error">
                    <error>Error message</error>
                  </response>
              

Delete a Reward

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

Notes:

• The ability to delete rewards is based on the permissions of the user_id that is making the call.
• When identifying the reward to the API, you MUST use the <id> that is returned in the XML constructs, NOT the <reward_id> which corresponds to an optional reward_identifier field.
• Only one reward can be deleted at a time. Loop this call in your program to delete multiple rewards.

Example PHP Request:

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

                  $data['user_id'] = 'john1970';
                  $data['user_password'] = '1959caadac9b13dcb3'; 
                  $data['type'] = 'campaign_delete';
                  $data['action'] = 'reward';
                  $data['account_id'] = 'greatwidgets';
                  $data['campaign_id'] = '1234567890123456';
                  $data['reward_id'] = '432';
              

Success XML Response:

                  <response status="success">
                      <reward status="deleted">
                        <id>432</id>
                      </reward>
                  </response>
              

Error XML Response:

                  <response status="error">
                    <error>Error message</error>
                  </response>
              

Delete a Promotion

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

Notes:

• The ability to delete promotions is based on the permissions of the user_id that is making the call.
• Only one promotion can be deleted at a time. Loop this call in your program to delete multiple promotions.

Example PHP Request:

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

                  $data['user_id'] = 'john1970';
                  $data['user_password'] = '1959caadac9b13dcb3'; 
                  $data['type'] = 'campaign_delete';
                  $data['action'] = 'promo';
                  $data['account_id'] = 'greatwidgets';
                  $data['campaign_id'] = '1234567890123456';
                  $data['promo_id'] = '543';
              

Success XML Response:

                  <response status="success">
                      <promo status="deleted">
                        <id>432</id>
                      </promo>
                  </response>
              

Error XML Response:

                  <response status="error">
                    <error>Error message</error>
                  </response>
              

Delete a BuyX Campaign Item

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

Notes:

• The ability to delete BuyX campaign items is based on the permissions of the user_id that is making the call.
• When identifying the item to the API with the parameter item_id, you MUST use the <id> that is returned in the XML construct as the result of a call like Campaign - List BuyX Items, NOT the <reward_id> which corresponds to the optional reward_identifier field.
• Only one item can be deleted at a time. Loop this call in your program to delete multiple items.

Example PHP Request:

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

                  $data['user_id'] = 'john1970';
                  $data['user_password'] = '1959caadac9b13dcb3'; 
                  $data['type'] = 'campaign_delete';
                  $data['action'] = 'item';
                  $data['account_id'] = 'greatwidgets';
                  $data['campaign_id'] = '1234567890123456';
                  $data['item_id'] = '678';
              

Success XML Response:

                  <response status="success">
                      <item status="deleted">
                        <id>432</id>
                      </item>
                  </response>
              

Error XML Response:

                  <response status="error">
                    <error>Error message</error>
                  </response>
              

Delete a Depreciation

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

Notes:

• The ability to delete depreciations is based on the permissions of the user_id that is making the call.
• When identifying the depreciation to the API, you must use the <id> that is returned in the XML constructs, for example from the Campaign - List Depreciations call
• Only one depreciation can be deleted at a time.

Example PHP Request:

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

                  $data['user_id'] = 'john1970';
                  $data['user_password'] = '1959caadac9b13dcb3'; 
                  $data['type'] = 'depreciation_delete';
                  $data['account_id'] = 'greatwidgets';
                  $data['campaign_id'] = '1234567890123456';
                  $data['fee_id'] = '456';
              

Success XML Response:

                  <response status="success">
                      <depreciation status="deleted">
                        <id>456</id>
                      </depreciation>
                  </response>
              

Error XML Response:

                  <response status="error">
                    <error>Error message</error>
                  </response>
              

Delete a Fee

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

Notes:

• The ability to delete a fee is based on the permissions of the user_id that is making the call.
• When identifying the depreciation to the API, you must use the <id> that is returned in the XML constructs, for example from the Campaign - List Fees call
• Only one fee can be deleted at a time.

Example PHP Request:

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

                  $data['user_id'] = 'john1970';
                  $data['user_password'] = '1959caadac9b13dcb3'; 
                  $data['type'] = 'campaign_fee_delete';
                  $data['account_id'] = 'greatwidgets';
                  $data['campaign_id'] = '1234567890123456';
                  $data['fee_id'] = '456';
              

Success XML Response:

                  <response status="success">
                      <fee status="deleted">
                        <id>456</id>
                      </fee>
                  </response>
              

Error XML Response:

                  <response status="error">
                    <error>Error message</error>
                  </response>
              

Deactivate a Campaign

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

Notes:

• The ability to deactivate campaigns is based on the permissions of the user_id that is making the call.
• Only one campaign can be deactivated at a time. Loop this call in your program to deactivate multiple campaigns.
• Deactivating a campaign removes it from the list of campaigns that is returned in many other calls, without deleting any data associated with it (settings, customer transactions, etc.) This is often used to "turn off" recurring seasonal campaigns.

Example PHP Request:

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

                  $data['user_id'] = 'john1970';
                  $data['user_password'] = '1959caadac9b13dcb3'; 
                  $data['type'] = 'campaign_deactivate';
                  $data['account_id'] = 'greatwidgets';
                  $data['campaign_id'] = '1234567890123456';
              

Success XML Response:

                  <response status="success">
                      <campaign>
                        <id>1234567890123456</id>
                      </campaign>
                  </response>
              

Error XML Response:

                  <response status="error">
                    <error>Error message</error>
                  </response>
              

Reactivate a Campaign

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

Notes:

• The ability to deactivate and reactivate campaigns is based on the permissions of the user_id that is making the call.
• Only one campaign can be reactivated at a time. Loop this call in your program to reactivate multiple campaigns.
• When reactivated a campaign will have retained any of its settings, customer transactions, etc. as when it was deactivated.

Example PHP Request:

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

                  $data['user_id'] = 'john1970';
                  $data['user_password'] = '1959caadac9b13dcb3'; 
                  $data['type'] = 'campaign_reactivate';
                  $data['account_id'] = 'greatwidgets';
                  $data['campaign_id'] = '1234567890123456';
              

Success XML Response:

                  <response status="success">
                      <campaign>
                        <id>1234567890123456</id>
                      </campaign>
                  </response>
              

Error XML Response:

                  <response status="error">
                    <error>Error message</error>
                  </response>