Mozido API Reference NAV Navbar
PHP

Overview

This page contains internal Loyalty APIs. Before using, the user must first Self Register and then authenticate using Get Token.

To help you get started with your integration, Cloud Payments provides a sample Postman collection that includes a template of all the Sticky Street API endpoints. It also includes a sample environment file with the URL details.

Click the button below to download the collection and associated the environment file.

image for Postman

Clients (Businesses)

Account - Update

Add a new reward to an existing Points or Event-based campaign. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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

$data['type'] = 'account_update';
$data['agency'] = 'demo_agency';
$data['contact_email'] = 'contact@demo_agency.com';
$data['contact_first_name'] = 'John';
$data['contact_last_name'] = 'Doe';
$data['contact_phone'] = '555-555-2455';
$data['client_email'] = 'john@widgets.com';
$data['biz_name'] = 'Great Widgets, LLC';
$data['biz_address1'] = '123 Success St.';
$data['biz_address2'] = 'Suite 103';
$data['biz_city'] = 'Anytown';
$data['biz_state'] = 'ZZ';
$data['biz_zip'] = '55555';
$data['biz_country'] = 'New Zealand';
$data['account_id'] = 'greatwidgets';
$data['account_password'] = 'pa$$w0rd';
$data['language_selector'] = 'EN';
$data['symbol_selector'] = 'AUD';
$data['timezone_selector'] = '68';
$data['referrer_name'] = 'John Smith';

Request Parameters

Parameter Name Example/Description Required
type account_update Yes
action Reward Yes
account_id Name of tenant Yes
agency demo_agency Only if Changed
contact_email info@agency.com Only if Changed
contact_first_name John Only if Changed
contact_last_name Doe Only if Changed
contact_phone 555-555-1212 Only if Changed
client_email john@widgits.com Only if Changed
biz_name Great Widgets, LLC Only if Changed
biz_address1 123 Success St. Only if Changed
biz_address2 Suite 103 Only if Changed
biz_city Anytown Only if Changed
biz_state ZZ Only if Changed
biz_zip 55555 Only if Changed
biz_country New Zealand Only if Changed
new_account_password pa$$w0rd Only if Changed
language_selector EN Only if Changed
symbol_selector AUD Only if Changed
timezone_selector 68 Only if Changed
referrer_name John Smith Only if Changed
activate Y Only if Changed
mailchimp_username monkeycall No
mailchimp_password b1zt3xt3r No
output JSON or XML No
If not provided, defaults to XML
callback someFunctionName No
JSONP format
condensed yes No
(No white space) Applies only to JSON(P) output

General Notes * The account_id cannot be changed -- It needs to be provided to identify which account is being edited. * 'agency' is the ID of the agency under which this client belongs. * The contact_ and biz_ fields are information about the client, except for the contact_email ( which is the agency's email contact -- this is due to historical and legacy billing reasons -- this is the email to which the bill is sent from the billing system.) * The client's email field is the client_email, NOT the contact_email (see above) * You can find a list of language two-letter codes in the Available Languages reference page. * You can find a list of currency codes in the Currency Codes reference page * You can find a list of timezone codes in the Timezones reference page * The activate parameter is optional and used only for those agencies that do not allow trial clients to automatically become billable once they pass 10 customers. For those agencies, specifying activate=Y will activate the trial client and allow them to pass the 10-customer limit. * Legacy use of type=process_owner_account, action=edit is still valid, but deprecated.

Success XML Response

 <response status="success?">
 </response>

Success XML Response (if user_id = account_id, then the user_password is new):

  <response status=`success`>
    <new_api_token>2959caadac9b13dcb4</new_api_token>
  </response>

Error XML Response:

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

Account - Information

Show a client's (store) account information: The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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

$data['type'] = 'account_info';
$data['account_id'] = 'greatwidgets';

Request Parameters

Parameter Name Example/Description Required
type account_info Yes
account_id Name of tenant Yes
output JSON or XML No
If not provided, defaults to XML
callback someFunctionName No
JSONP format
condensed yes No
(No white space) Applies only to JSON(P) output

Success XML Response (New or Updated Account):

<response status=`success`>
  <account>
    <account_id>test2009050502</account_id>
    <biz_name>Great Widgets Company</biz_name>
    <biz_address1>123 Main St.</biz_address1>
    <biz_address2></biz_address2>
    <biz_city>Anytown</biz_city>
    <biz_state>CA</biz_state>
    <biz_zip>55555</biz_zip>
    <biz_country></biz_country>
    <contact_first_name>John</contact_first_name>
    <contact_last_name>Smith</contact_last_name>
    <contact_email>John@email.com</contact_email>
    <contact_phone>555-555-5555</contact_phone>
    <language>EN</language>
    <symbol>USD</symbol>
    <glyph>$</glyph>
    <timezone>14</timezone>
    <created>2010-09-05</created>
  </account>
</response>

Error XML Response

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

Dashboard - Information

Show a client's (store's) account information: The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Request Parameters

Name Example/Description Required
API 1.5 Yes
Account_id Name of tenant Yes
Type dashboard Yes
most_active 10 (customers) No
customer_count Yes No
total_customers_this_month Yes No
total_transactions_this_month Yes No
active_campaigns_count Yes No
campaigns_per_day_activity 30 (days) No
last_X_transactions 10 (transactions) No
last_X_customers 10 (customers) No
output JSON or XML No
If not provided, defaults to XML
callback someFunctionName No
JSONP format
condensed yes No
(No white space) Applies only to JSON(P) output

General Notes: * The information returned depends on the permissions of the user. For example, if a user only has access to one campaign out of many, the total transactions, or last X transactions, etc. will have a lower quantity than if a user with more permissions made this API call. * most_active the number of most active customers to list * customer_count return the total customer count for the account. * total_customers_this_month - return a summary of: * New customers this month so far. * New customers all of last month. * New customers last month in the same period as this month. * total_transactions_this_month - returns a summary of: * Number of transactions this month so far. * Number of transactions all of last month. * Number of transactions last month in the same period as this month. * active_campaigns_count How many active campaigns (affected by user permissions) * campaigns_per_day_activity A summary per campaign of the number of transactions per day for the number of days specified. * last_X_transactions Summary info of the number of transactions specified. * last_X_customers Summary into of the number of customers specified.

Dashboard Example PHP Request

If you are using PHP request, 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'] = 'dashboard';
$data['most_active'] = '10';
$data['customer_count'] = 'Yes';
$data['total_customers_this_month'] = '10';
$data['total_transactions_this_month'] = '10';
$data['active_campaign_count'] = 'Yes';
$data['campaigns_per_day_activity'] = '30';
$data['last_X_transactions'] = '10';
$data['last_X_customers'] = '10';

Dashboard Example PHP Success XML Response (New or Updated Account):

<response status=`success`>
  <most_active>
    <customer>
      <code>12345678900123456</code>
      <card_number>16846</card_number>
      <first_name>John</first_name>
      <last_name>Smith</last_name>
      <transactions>124</transactions>
    </customer>
    ...
  </most_active>
  <total_customers>
    <all_time>2845</all_time>
    <this_month>276</this_month>
    <last_month>498</last_month>
    <same_period_last_month>248</same_period_last_month>
  </total_customers>
  <total_transactions>
    <this_month>8905</this_month>
    <last_month>10567</last_month>
    <same_period_last_month>9025</same_period_last_month>
  </total_transactions>
  <active_campaigns_count>5</active_campaigns_count>
  <campaigns_per_day_activity>
    <campaign>
      <campaign_id>1234567890543216</campaign_id>
      <campaign_name>Points Campaign</campaign_name>
      <campaign_type>points</campaign_type>
      <day>
        <date>2013-05-10</date>
        <quantity>157</quantity>
      </day>
      ...
    </campaigns>
    ...
  </campaigns_per_day_activity>
  <last_X_transactions>
    <transactions>10</transactions>
    <transaction>
      <transaction_id>123456</transaction_id>
      <campaign_id>1234567890543216</campaign_id>
      <campaign_name>Points Campaign</campaign_name>
      <campaign_type>points</campaign_type>
      <code>12345678900123456</code>
      <card_number>16846</card_number>
      <first_name>John</first_name>
      <last_name>Smith</last_name>
      <date>2013-05-10</date>
      <amount>1500</amount>
      <redeemed>N</redeemed>
      <item></item>
      <description>Smith</description>
      <user>cashier123</user>
    </transaction>
    ...
  </last_X_transactions>
  <last_X_customers>
    <customer>
      <code>12345678900123456</code>
      <card_number>16846</card_number>
      <first_name>John</first_name>
      <last_name>Smith</last_name>
      <time_stamp>2013-05-10 13:14:56</time_stamp>
    </customer>
    ...
  </last_X_customers>
</response>

Dashboard Example PHP Error XML Response:

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

Custom Fields

Customer Field - Create

Create a new field used to gather customer data. The data to be submitted to the API is composed of the following fields that are common to all campaign types:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Customer Fields - Create PHP Requests

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

$data['API'] = '1.5';
$data['user_api_key'] = '1959caadac9b13dcb3';
$data['account_id'] = 'greatwidgets';
$data['type'] = 'manage_fields';
$data['action'] = 'add';
$data['country_show'] = 'N';
$data['custom_field_2_label'] = 'Middle Name'
$data['custom_field_2_show'] = 'Y';
$data['custom_field_2_type'] = 'Text';
$data['custom_field_3_label'] = 'Tags';
$data['custom_field_3_show'] = 'Y';
$data['custom_field_3_type'] = 'List';
$data['custom_field_3_choices'] = 'Tag A, Tag B, Tag C, Tag D, ...';
$data['custom_field_4_label'] = 'Allow SMS';
$data['custom_field_4_show'] = 'Y';
$data['custom_field_4_type'] = 'Pick';
$data['custom_field_4_choices'] = 'Yes|No';

Request Parameters

Name Description/Example Required
API 1.6 Yes
account_id Name of tenant. Yes
action add Yes
type manage_fields Yes
custom_field_#_label greatwidgets No
custom_field_#_show N Yes
custom_field_#_type List Yes
custom_field_#_choices Single, Married, Other No
custom_field_#_searchable Y No
custom_field_#_unique Y No
output JSON or XML No
If not provided, defaults to XML
callback someFunctionName No
JSONP format
condensed yes No
(No white space) Applies only to JSON(P) output

General Notes: * Only users with proper permissions can access this call. * Multiple fields can be added at the same time. * If a field received by the API is missing some of its parameters, it will be created with the missing values set to their default value: Show=No, Type=Text. * Additional fields have the following [field_name_#] structure: * custom_field_# where the # is any integer above 1
because one of the pre-existing fields is already custom_field_1)
Example: * custom_field_2 * custom_field_14 * ...

Create Customer Field Success XML Response (lists ALL the existing fields)

<response status="success">
    <account>
          <account_id>test2009050502</account_id>
          <fields>
              <field>
              <name>card_number</name>
              <label>Member #</label>
              <show>Y</show>
              <type>Text</type>
          </field>
          <field>
              <name>first_name</name>
              <label>First Name</label>
              <show>Y</show>
              <type>Text</type>
              </field>
              ...
          <field>
              <name>custom_field_2</name>
              <label>Middle Name</label>
              <show>Y</show>
              <type>Text</type>
          </field>
          <field>
              <name>custom_field_3</name>
              <label>Tags</label>
              <show>Y</show>
              <type>List</type>
              <choices>
                <choice>Tag A</choice>
                <choice>Tag B</choice>
                <choice>Tag C</choice>
              </choice>
          </field>
          <field>
              <name>custom_field_4</name>
              <label>Allow SMS</label>
              <show>Y</show>
              <type>Pick</type>
              <choices>
                <choice>Yes</choice>
                <choice>No</choice>
              </choice>
            </field>
          </fields>
      </account>
</response>

Create Customer Field Error XML Response


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

Customer Fields - List

Show the fields used to gather customer data: The data to be submitted to the API is composed of the following fields that are common to all campaign types:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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

$data['user_api_key'] = '1959caadac9b13dcb3';
$data['account_id'] = 'greatwidgets';
$data['type'] = 'manage_fields';
$data['action'] = 'list';

Request Parameters

Parameter Name Description/Example Required
API 1.6 Yes
type manage_fields Yes
account_id Name of tenant. Yes
action list Yes
output JSON or XML No
If not provided, defaults to XML
callback someFunctionName No
JSONP format
condensed yes No
(No white space) Applies only to JSON(P) output

General Notes: * Almost all users can access this call.

Success XML Response (lists ALL the existing fields):

<response status="success">
  <account>
    <account_id>test2009050502</account_id>
    <fields>
      <field>
        <name>card_number</name>
        <label>Card #</label>
        <show>Y</show>
        <type>Text</type>
      </field>
      <field>
        <name>custom_field_2</name>
        <label>Marital Status</label>
        <show>Y</show>
        <type>List</type>
        <choices>
          <choice>Single</choice>
          <choice>Married</choice>
          <choice>Divorced</choice>
          <choice>In Civil Union</choice>
          <choice>Other</choice>
        </choices>
      </field>
      ...
    </fields>
  </account>
</response>

Notes: * The show response indicates whether or not this field ought to be shown or not. Usually fields with N will have nothing in them. However, it is allowed to add content to any defined field through the API regardless of their show status. * The type parameter can be: Text, Date, List (Multiple Choice), or Pick (Single Choice)

Error XML Response

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

Customer Field - Update

Update the status of fields used to gather customer data:

The data to be submitted to the API is composed of the following fields that are common to all campaign types:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example Request 1

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

$data['API'] = '1.5';
$data['user_id'] = 'john1970';
$data['user_api_key'] = '1959caadac9b13dcb3';
$data['account_id'] = 'greatwidgets';
$data['type'] = 'manage_fields';
$data['action'] = 'update';
$data['card_number_label'] = 'Member #';
$data['card_number_show'] = 'Y';
$data['country_show'] = 'N';
$data['custom_field_3_label'] = 'Gender';
$data['custom_field_3_show'] = 'Y';
$data['custom_field_3_type'] = 'Pick';
$data['custom_field_3_choices'] = 'Male, Female, Other';
$data['custom_field_4_label'] = 'Allow SMS';
$data['custom_field_4_show'] = 'Y';
$data['custom_field_4_type'] = 'Text';

Success XML Response from Example 1 - (lists ALL existing fields):

<response status="success">
    <account>
          <account_id>test2009050502</account_id>
          <fields>
              <field>
              <name>card_number</name>
              <label>Member #</label>
              <show>Y</show>
              <type>Text</type>
          </field>
          <field>
              <name>first_name</name>
              <label>First Name</label>
              <show>Y</show>
              <type>Text</type>
              </field>
              ...
          <field>
              <name>custom_field_2</name>
              <label>Middle Name</label>
              <show>Y</show>
              <type>Text</type>
          </field>
          <field>
              <name>custom_field_3</name>
              <label>Tags</label>
              <show>Y</show>
              <type>List</type>
              <choices>
                <choice>Tag A</choice>
                <choice>Tag B</choice>
                <choice>Tag C</choice>
              </choice>
          </field>
          <field>
              <name>custom_field_4</name>
              <label>Allow SMS</label>
              <show>Y</show>
              <type>Pick</type>
              <choices>
                <choice>Yes</choice>
                <choice>No</choice>
              </choice>
            </field>
          </fields>
      </account>
</response>

Notes: * The show response indicates whether or not this field should be shown or not. Usually fields with N will have nothing in them. However, it is allowed to add content to any defined field through the API regardless of their show status.

Example Request 2

No fields are passed, and web_update+ is set to Y (ie: All fields are unchecked -- Not likely but given as an extreme example):

$data['API'] = '1.5';
$data['user_id'] = 'john1970';
$data['user_api_key'] = '1959caadac9b13dcb3';
$data['type'] = 'manage_fields';
$data['action'] = 'update';
$data['account_id'] = 'greatwidgets';
$data['web_update'] = 'Y';

Success XML Response from Example 2

<response status="success">
  <account>
      <account_id>test2009050502</account_id>
      <fields>
        <field>
          <id>card_number</name>
          <label>Card #</label>
          <show>N</show>
        </field>
        <field>
          <id>first_name</name>
          <label>First Name</label>
          <show>N</show>
        </field>
        ...
      </fields>
    </account>
</response>

Request Parameters

Parameter Name Description/Example Required
API 1.6 Yes
account_id Name of tenant. Yes
action update Yes
type manage_fields Yes
custom_field_#_label greatwidgets No
custom_field_#_show N No
custom_field_#_type List See Note
custom_field_#_choices Single, Married, Other No
custom_field_#_searchable Y No
custom_field_#_unique Y No
web_update Y No
output JSON or XML No
If not provided, defaults to XML
callback someFunctionName No
JSONP format
condensed yes No
(No white space) Applies only to JSON(P) output

Error XML response

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

Customer Field - Delete

Delete a Customer field removes an existing field used for gathering customer data. The data submitted is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
Api-Key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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


    $data['API'] = '1.5';
    $data['user_api_key'] = '1959caadac9b13dcb3';
    $data['account_id'] = 'greatwidgets';
    $data['type'] = 'manage_fields';
    $data['action'] = 'delete';
    $data['field_list'] = 'custom_field_3|custom_field_4';

Request Parameters

Parameter Name Required Description/Example
API Yes 1.6
Account_id Yes Name of tenant.
Action Yes delete
Type Yes manage_fields
field_list Yes custom_field_3
output No
If not provided, defaults to XML		 JSON or XML
callback No
JSONP format		 someFunctionName
condensed No
(No white space) Applies only to JSON(P) output		 yes

General Notes: * Only users with proper permissions can access this call. * Multiple fields can be deleted at the same time. * The following default field_names cannot be deleted, but you can update them to show=N. * card_number * first_name * last_name * phone * email * street1 * street2 * city * state * zip * country * customer_username * customer_PIN * customer_password * custom_date * custom_field_1

Create Customer Field Success XML Response (lists ALL the existing fields)


    <response status="success">
    <account>
    <account_id>test2009050502</account_id>
    <fields>
    <field>
    <name>card_number</name>
    <label>Member #</label>
    <show>Y</show>
    <type>Text</type>
    </field>
    <field>
    <name>first_name</name>
    <label>First Name</label>
    <show>Y</show>
    <type>Text</type>
    </field>
    ...
    <field>
    <name>custom_field_2</name>
    <label>Middle Name</label>
    <show>Y</show>
    <type>Text</type>
    </field>
    </fields>
    </account>
    </response>

Delete Customer Field Error XML Response


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

Transaction Field - Create

Create a new field used when recording customer transactions: The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Request Parameters

Parameter Name Description/Example Required
API 1.6 Yes
account_id Name of tenant. Yes
action add Yes
type transaction_fields Yes
custom_field_#_label greatwidgets No
custom_field_#_show N No
custom_field_#_type List Yes
custom_field_#_choices Single, Married, Other No
custom_field_#_unique Y No
output JSON or XML No
If not provided, defaults to XML
callback someFunctionName No
JSONP format
condensed yes No
(No white space) Applies only to JSON(P) output

General Notes:

Example Request

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

$data['API'] = '1.5';
$data['user_api_key'] = '1959caadac9b13dcb3';
$data['account_id'] = 'greatwidgets';
$data['type'] = 'transaction_fields';
$data['action'] = 'add';
$data['custom_field_1_label'] = 'Item SKU'
$data['custom_field_1_show'] = 'Y';
$data['custom_field_1_type'] = 'Text';
$data['custom_field_2_label'] = 'Tags';
$data['custom_field_2_show'] = 'Y';
$data['custom_field_2_type'] = 'List';
$data['custom_field_2_choices'] = 'Tag A|Tag B|Tag C|Tag D|...';
$data['custom_field_3_label'] = 'Condition';
$data['custom_field_3_show'] = 'Y';
$data['custom_field_3_type'] = 'Pick';
$data['custom_field_3_choices'] = 'New|Used|Other';
$data['custom_field_4_label'] = 'Expiration Date';
$data['custom_field_4_show'] = 'Y';
$data['custom_field_4_type'] = 'Date';
$data['custom_field_5_label'] = 'Kilograms';
$data['custom_field_5_show'] = 'Y';
$data['custom_field_5_type'] = 'Number';

Success XML Response (lists ONLY the custom fields added):

<response status="success">
  <account>
    <account_id>test2009050502</account_id>
    <fields>
      <field>
        <name>custom_field_1</name>
        <label>Item SKU</label>
        <show>Y</show>
        <type>Text</type>
      </field>
      <field>
        <name>custom_field_2</name>
        <label>Tags</label>
        <show>Y</show>
        <type>List</type>
        <choices>
          <choice>Tag A</choice>
          <choice>Tag B</choice>
          <choice>Tag C</choice>
        </choice>
      </field>
      <field>
        <name>custom_field_3</name>
        <label>Condition</label>
        <show>Y</show>
        <type>Pick</type>
        <choices>
          <choice>New</choice>
          <choice>Used</choice>
          <choice>Other</choice>
        </choice>
      </field>
      <field>
        <name>custom_field_4</name>
        <label>Expiration Date</label>
        <show>Y</show>
        <type>Date</type>
      </field>
      <field>
        <name>custom_field_5</name>
        <label>Kilograms</label>
        <show>Y</show>
        <type>Number</type>
      </field>
    </fields>
<name></name>/account>
</response>

NOTE: * The show response indicates whether or not this field ought to be shown or not. Usually fields with N will have nothing in them. However, it is allowed to add content to any defined field through the API regardless of their show status.

Error XML response

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

Transaction Fields - List

List all the custom fields used when recording customer transactions: The data to be submitted to the API is composed of the following fields that are common to all campaign types:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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

$data['API'] = '1.5';
$data['user_api_key'] = '1959caadac9b13dcb3';
$data['account_id'] = 'greatwidgets';
$data['type'] = 'transaction_fields';
$data['action'] = 'list';

Request Parameters

Parameter Name Description/Example Required
API 1.6 Yes
type users_list Yes
account_id Name of tenant. Yes
action list Yes
output JSON or XML No
If not provided, defaults to XML
callback someFunctionName No
JSONP format
condensed yes No
(No white space) Applies only to JSON(P) output

General Notes: * Almost all users can access this call. * This call returns ONLY the ADDITIONAL custom fields, and NOT the regular predefined ones. ie: Only fields whose field_name conform to the custom_field_#` format are returned.

Success XML Response (lists ALL the existing fields):

<response status="success">
  <account>
    <account_id>test2009050502</account_id>
    <fields>
      <field>
        <name>custom_field_1</name>
        <label>Customer ID</label>
        <show>Y</show>
        <type>Text</type>
        <unique>Yes</unique>
      </field>
      <field>
        <name>custom_field_2</name>
        <label>Tags</label>
        <show>Y</show>
        <type>List</type>
        <choices>
          <choice>Tag A</choice>
          <choice>Tag B</choice>
          <choice>Tag C</choice>
          </choice>
        </field>
        <field>
          <name>custom_field_3</name>
          <label>Condition</label>
          <show>Y</show>
          <type>Pick</type>
          <choices>
            <choice>New</choice>
            <choice>Used</choice>
            <choice>Other</choice>
          </choice>
        </field>
        <field>
          <name>custom_field_4</name>
          <label>Expiration Date</label>
          <show>Y</show>
          <type>Date</type>
        </field>
        <field>
          <name>custom_field_5</name>
          <label>Kilograms</label>
          <show>Y</show>
          <type>Number</type>
        </field>
    </account>
  </response>

Notes: * The show response indicates whether or not this field ought to be shown or not. Usually fields with N will have nothing in them. However, it is allowed to add content to any defined field through the API regardless of their show status.

Error XML Response:

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

Transaction Field - Update

Update fields used when recording customer transactions:

The data to be submitted to the API is composed of the following fields that are common to all campaign types:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

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

$data['API'] = '1.5';
$data['user_api_key'] = '1959caadac9b13dcb3';
$data['account_id'] = 'greatwidgets';
$data['type'] = 'transaction_fields';
$data['action'] = 'update';
$data['custom_field_1_label'] = 'SKU'
$data['custom_field_2_show'] = 'N';
$data['custom_field_6_label'] = 'New Field';
$data['custom_field_6_show'] = 'Y';
$data['custom_field_6_type'] = 'Text';

Request Parameters

Parameter Name Description/Example Required
API 1.6 Yes
account_id Name of tenant. Yes
action update Yes
type transaction_fields Yes
custom_field_#_label Item SKU No
custom_field_#_show Y No
custom_field_#_type Text See Note
custom_field_#_choices New, Used, Other No
web_update Y No
output JSON or XML No
If not provided, defaults to XML
callback someFunctionName No
JSONP format
condensed yes No
(No white space) Applies only to JSON(P) output

General Notes: * Only users with proper permissions can access this call. * Multiple fields can be updated at the same time. * {field_name}_type and {field_name}_unique will be ignored if the field to be updated already exists (as it should in an update API call -- however, it is allowed to be passed in case the update is done blindly without the ability to know if the field already exists or not, in which case it would be added, and that requires the type to be set, and perhaps if that field is to be unique or not, since the these can only be set when a field is created. * Only Text type fields can be set to searchable. All custom fields are searchable with the Customer - Find and Customer - Search API calls. This setting applies only to certain situations, like coalition accounts, where the ability to pull up a customer record is limited by the user's permissions. This field allows to mark a field as being like an ID field in that a user can pull up this customer in a coalition account even though the customer doesn't yet belong to that campaign. In non-coalition situations, this would enable the user of Master/Slave customer IDs that allow multiple customers (family, businesses) to earn in a single customer account. * If using this call as part of a web-based HTML form where users tick checkboxes to select which fields to show, the HTML form will only send back those fields whose boxes are checked. (ie: unchecking a box means that no data is sent back and is essentially the same as the option having never been given.) To solve that issue, either make sure to develop code to still send any unchecked field with its value set to N, OR include the web_udate=Y option which will cause the API to treat any non-submitted choice (unchecked) as having been assigned the value of N (This works only on existing fields, because it assumes that those that are missing are those that are unchecked.) * If a field is received by the API to be updated and does not already exist, it will be created with any values provided (Default: Show=No, if it's not provided.) WARNING: This will NOT happen if a type is not provided, and you cannot change the type once it's set.

Success XML Response (lists ALL the existing fields):

<response status="success">
  <account>
    <account_id>test2009050502</account_id>
    <fields>
      <field>
        <name>custom_field_1</name>
        <label>ID</label>
        <show>Y</show>
        <type>Text</type>
        <unique>Yes</unique>
      </field>
      <field>
        <name>custom_field_2</name>
        <label>Tags</label>
        <show>N</show>
        <type>List</type>
        <choices>
          <choice>Tag A</choice>
          <choice>Tag B</choice>
          <choice>Tag C</choice>
        </choice>
      </field>
      <field>
        <name>custom_field_3</name>
        <label>Condition</label>
        <show>Y</show>
        <type>Pick</type>
        <choices>
          <choice>New</choice>
          <choice>Used</choice>
          <choice>Other</choice>
        </choice>
      </field>
      <field>
        <name>custom_field_4</name>
        <label>Expiration Date</label>
        <show>Y</show>
        <type>Date</type>
      </field>
      <field>
        <name>custom_field_5</name>
        <label>Kilograms</label>
        <show>Y</show>
        <type>Number</type>
      </field>
      <field>
        <name>custom_field_6</name>
        <label>New Field</label>
        <show>Y</show>
        <type>Text</type>
      </field>
    </fields>
  </account>
</response>

Notes: * The show response indicates whether or not this field ought to be shown or not. Usually fields with N will have nothing in them. However, it is allowed to add content to any defined field through the API regardless of their show status.

Error XML response

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

Transaction Field - Delete

Delete existing fields used when recording customer transactions:

The data to be submitted to the API is composed of the following fields that are common to all campaign types:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example Request

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

$data['API'] = '1.6';
$data['user_api_key'] = '1959caadac9b13dcb3';
$data['account_id'] = 'greatwidgets';
$data['type'] = 'transaction_fields';
$data['action'] = 'delete';
$data['field_list'] = 'custom_field_3|custom_field_4'

Request Parameters

Parameter Name Description/Example Required
API 1.6 Yes
account_id Name of tenant. Yes
action delete Yes
type transaction_fields Yes
field_list custom_field_3
custom_field_4		 Yes
output JSON or XML No
If not provided, defaults to XML
callback someFunctionName No
JSONP format
condensed yes No
(No white space) Applies only to JSON(P) output

General Notes:

Success XML Response (lists ONLY the remaining custom fields added):

<response status="success">
  <account>
    <account_id>test2009050502</account_id>
    <fields>
        <field>
          <name>custom_field_1</name>
          <label>Item SKU</label>
          <show>Y</show>
          <type>Text</type>
      </field>
      <field>
        <name>custom_field_2</name>
        <label>Tags</label>
        <show>Y</show>
        <type>List</type>
        <choices>
          <choice>Tag A</choice>
          <choice>Tag B</choice>
          <choice>Tag C</choice>
        </choice>
      </field>
      <field>
        <name>custom_field_5</name>
        <label>Kilograms</label>
        <show>Y</show>
        <type>Number</type>
      </field>
    </fields>
  </account>
</response>

Error XML Response

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

Users (Business Employees)

User - New

Create a new user for an account. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

If you are using PHP for a request, the $data array would look like:

$data['type'] = 'user_new';
$data['account_id'] = 'greatwidgets';
$data['user_name'] = 'janeclerk';
$data['user_new_password'] = 'pa$$w0rd';
$data['user_first_name'] = 'Jane';
$data['user_last_name'] = 'Doe';
$data['user_custom1'] = 'Melbourne Office';
$data['language_selector'] = 'EN';
$data['timezone_selector'] = '68';
$data['user_role'] = 'K';
$data['allowed_campaigns'] = '12971184024723,0239471023412';
or
$data['allowed_campaigns'] = 'all';
or
$data['allowed_campaigns'] = 'none';

Request Parameters

Parameter Name Example/Description Required
type user_new Yes
account_id Name of tenant Yes
user_name janeclerk Yes
user_new_password pa$$wo0rd Yes
user_first_name Jane Optional
user_last_name Doe Optional
user_custom1 Melbourne Office Optional
user_PIN 1234 Optional
language_selector EN Optional
timezone_selector 68 Optional
user_role K Yes
allowed_campaigns all or campaign id(s) or none Yes
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

General Notes * The user_name cannot be longer than 20 characters and must contain only alphanumeric characters and the underscore (_) * The user_PIN is an API-specific field made available for custom applications such as a physical terminal. It cannot be defined or edited in the web interface. It MUST be unique to each user within an account. * You can find a list of language two-letter codes in the Available Languages reference page * You can find a list of timezone codes in the Timezones reference page * The allowed_campaigns consists of (see examples below) : * A single entry all * A single entry none * Multiple entries of campaign IDs separated by a comma , * Administrator (A) users are not affected by this parameter and are always set to access all campaigns. * The user_role is based on the roles listed in the User Permission Levels reference page. * The user_custom1 field is shown on the Dashboard as Location and on XML results from the API as the user_addtl_info tag.

Success XML Response (New / Updated User)

  <response status="success">
  </response>

Error XML Response:

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

User - Update

Update an account user's information.

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

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

If you are using PHP for a request, the $data array would look like:

$data['type'] = 'process_user';
$data['account_id'] = 'greatwidgets';
$data['user_action'] = 'new';
$data['user_name'] = 'janeclerk';
$data['user_password1'] = 'pa$$w0rd';
$data['user_password2'] = 'pa$$w0rd';
$data['user_first_name'] = 'Jane';
$data['user_last_name'] = 'Doe';
$data['user_custom1'] = 'Melbourne Office';
$data['language_selector'] = 'EN';
$data['timezone_selector'] = '68';
$data['user_role'] = 'K';
$data['allowed_campaigns'] = '12971184024723,0239471023412';
or
$data['allowed_campaigns'] = 'all';
or
$data['allowed_campaigns'] = 'none';

Request Parameters

Parameter Name Example/Description Required
type user_update Yes
account_id Name of tenant Yes
user_name janeclerk Yes
user_new_password pa$$wo0rd Optional
user_first_name Jane Optional
user_last_name Doe Optional
user_custom1 Melbourne Office Optional
user_PIN 1234 Optional
language_selector EN Optional
language_custom Yes or No Optional
timezone_selector 68 Optional
user_role K Optional
allowed_campaigns all or campaign id(s) or none Optional
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

Success XML Response (New / Updated User)

  <response status="success">
  </response>

Error XML Response:

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

Users - List

Returns a list of the users for an account. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Request for a full, unordered list of all users without permissions details: If you are using PHP for a request, the $data array would look like:

$data['API'] = '1.5';
$data['account_id'] = 'greatwidgets';
$data['type'] = 'users_list';

Example PHP Request for a partial, ordered list matching users with permissions details: If you are using PHP for a request, the $data array would look like:

$data['API'] = '1.5';
$data['account_id'] = 'greatwidgets';
$data['type'] = 'users_list';
$data['searchField'] = 'user_custom1';
$data['searchOper'] = 'cn';
$data['searchOper'] = 'London';
$data['sortField'] = 'user_first_name';
$data['sortOrder'] = 'ASC';
$data['offset'] = '0';
$data['length'] = '10';
$data['show_permissions'] = 'Yes';

Request Parameters

Parameter Name Example/Description Required
API 1.6 Yes
type user_update Yes
account_id Name of tenant Yes
user_name janeclerk Yes
user_new_password pa$$wo0rd Optional
user_first_name Jane Optional
user_last_name Doe Optional
user_custom1 Melbourne Office Optional
user_PIN 1234 Optional
language_selector EN Optional
language_custom Yes or No Optional
timezone_selector 68 Optional
user_role K Optional
allowed_campaigns all or campaign id(s) or none Optional
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

Success XML Response (New / Updated User)

<response status="success">
  <pagination>
    <total>12</total>
  </pagination>
  <users>
    <user>
      <user_id>janecashier</user_id>
      <user_first_name>Jane</user_first_name>
      <user_last_name>Cashier</user_last_name>
      <user_api_key>p2345khkl235hkufbfdivsdf</user_api_key>
      <user_PIN>1234</user_PIN>
      <user_addtl_info>London</user_addtl_info>
      <user_language>EN<user_language>
      <user_timezone>15</user_timezone>
      <user_role>K</user_role>
      <user_allowed_campaigns status="some">
        <campaign_id>1234567890123456</campaign_id>
        <campaign_id>2345678901234567</campaign_id>
        ...
      </user_allowed_campaigns>
    </user>
    <user>
      <user_id>joeclerky</user_id>
      <user_first_name>Joe</user_first_name>
      <user_last_name>Clerky</user_last_name>
      <user_password>p4sf8nvrdr8vhsd98erkerte</user_password>
      <user_PIN>9876</user_PIN>
      <user_addtl_info>New York</user_addtl_info>
      <user_language>EN<user_language>
      <user_timezone>15</user_timezone>
      <user_role>K</user_role>
      <user_allowed_campaigns status="all">
      </user_allowed_campaigns>
    </user>
    ...
  </users>
</response>

Notes: * - The user_allowed_campaigns status can consisting of: - all to indicated that all campaigns are allowed access - none to indicate no access to none of the account campaigns (rare) - some to indicate multiple entries of campaign IDs (as in example above)

Success XML Response (New / Updated User)

<response status="success">
  <pagination>
    <total>5</total>
    <offset>0</offset>
    <length>10</length>
  </pagination>
  <users>
    <user>
      <user_id>janecashier</user_id>
      <user_first_name>Jane</user_first_name>
      <user_last_name>Cashier</user_last_name>
      <user_api_key>p2345khkl235hkufbfdivsdf</user_api_key>
      <user_PIN>1234</user_PIN>
      <user_addtl_info>London</user_addtl_info>
      <user_language>EN<user_language>
      <user_timezone>15</user_timezone>
      <user_role>K</user_role>
      <user_permissions>
        <view_account_info>Yes</view_account_info>
        <view_promotions>Yes</view_promotions>
        ...
      </user_permissions>
      <user_allowed_campaigns status="some">
        <campaign_id>1234567890123456</campaign_id>
        <campaign_id>2345678901234567</campaign_id>
        ...
      </user_allowed_campaigns>
    </user>
    ...
  </users>
</response>

Error XML Response:

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

User - Info

Returns information about a user of the account.

When no other user is specified, it returns information about the user_id used to make the API calls. Mostly used for continuous validation of a user past the login screen on front-end store applications, since incorrect credentials will return an error message, and correct ones will return information about the user including their permissions level which could be tainted if stored in a cookie or as hidden form data.

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

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Request: If you are using PHP for a request, the $data array would look like:

$data['type'] = 'user_info';
$data['account_id'] = 'greatwidgets';

Request Parameters

Parameter Name Example/Description Required
API 1.1 Yes
type user_info Yes
account_id Name of tenant Yes
user_name clerk33 Optional
suppress_permissions Yes Optional
terminal Yes Optional
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

Success XML Response (Account Owner credentials only)

<response status="success">
  <user>
    <user_id>johnnyclerk</user_id>
    <user_is_owner>true</user_is_owner>
    <user_biz_name>Demo Co.</user_biz_name>
    <user_language>EN</user_language>
    <user_timzone>14</user_timezone>
    <user_level>A</user_level>
  </user>
</response>

Notes - Account Owner user accounts do not have first_name, last_name, or addtl_info fields - Account Owners are always level A. This is included even if not needed to simplify permission checks at the application / integration level. - Timezone and language code tables are available on the menu on the left.entries of campaign IDs (as in example above)

Success XML Response (Account Users credentials)

php <response status="success"> <user> <user_id>johnnyclerk</user_id> <user_is_owner>false</user_is_owner> <user_first_name>John</user_first_name> <user_last_name>Smith</user_last_name> <user_addtl_info>store 35</user_addtl_info> <user_language>EN</user_language> <user_timzone>14</user_timezone> <user_level>K</user_level> </user> </response> Notes: - Account Users do not have a biz_name field. - timezone , language, and user_level code tables are available on the menu on the left.

Error XML Response:

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

User - Add to Campaign

Allows a batch (list) of users to be given permission to access a particular campaign all at once.

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

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Request: If you are using PHP for a request, the $data array would look like:

$data['API'] = '1.5';
$data['account_id'] = 'greatwidgets';
$data['type'] = 'campaign_users';
$data['action'] = 'add';
$data['campaign_id'] = '1234567890123456';
$data['users_list'] = 'user1,user2,user3,user4,user5';

Request Parameters

Parameter Name Example/Description Required
API 1.6 Yes
account_id Name of tenant Yes
type campaign_users Yes
action add Yes
campaign_id 01234567890123456 Yes
users_list user1, user2, user3, etc Yes
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

General Notes - There must be only ONE campaign_id. - The usernames in the users_list must be separated by a comma. Extra spaces will be trimmed, so don't worry about them.

Success XML Response

<response status="success">
  <users_added>
    <user>user1</user>
    <user>user2</user>
    <user>user3</user>
    <user>user5</user>
  </users_added>
</response>

Notes - Only the users that were actually added that campaign's access permissions will be shown on the return XML. The following are reasons why a username is not returned: - The username is not valid, does not exist, or not associated with the account_id given. - The username already has permissions to access the campaign_id given. - The username is the owner id, which always has access to all campaigns.

Error XML Response:

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

User - Delete

Deletes or marks as deleted a particular account user.

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

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Request: If you are using PHP for a request, the $data array would look like:

$data['type'] = 'user_delete';
$data['account_id'] = 'greatwidgets';
$data['user_name'] = 'fired_clerk';

Request Parameters

Parameter Name Example/Description Required
type user_delete Yes
account_id Name of tenant Yes
user_name fired_clerk Yes
action permanent Optional
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

Success XML Response

  <response status="success">
  </response>

Error XML Response:

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

User - Remove from Campaign

Allows a batch (list) of users to be removed from having permission to access a particular campaign. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Request If you are using PHP for a request, the $data array would look like:

$data['API'] = '1.5';
$data['account_id'] = 'greatwidgets';
$data['type'] = 'campaign_users';
$data['action'] = 'remove';
$data['campaign_id'] = '1234567890123456';
$data['users_list'] = 'user1,user2,user3,user4,user5';

Request Parameters

Parameter Name Example/Description Required
API 1.6 Yes
account_id Name of tenant Yes
type campaign_users Yes
action remove Yes
campaign_id 01234567890123456 Yes
users_list user1, user2, user3, etc Yes
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

General Notes - There must be only ONE campaign_id. - The usernames in the users_list must be separated by a comma. Extra spaces will be trimmed, so don't worry about them.

Success XML Response

<response status="success">
  <users_removed>
    <user>user1</user>
    <user>user2</user>
    <user>user3</user>
    <user>user5</user>
  </users_removed>
</response>

Notes - Only the users that were actually removed that campaign's access permissions will be shown on the return XML. The following are reasons why a username is not returned: - The username is not valid, does not exist, or not associated with the account_id given. - The username already has permissions to access the campaign_id given. - The username is the owner id, which always has access to all campaigns.

Error XML Response:

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

Example PHP Request: If you are using PHP for a request, the $data array would look like:

$data['API'] = '1.5';
$data['account_id'] = 'greatwidgets';
$data['type'] = 'campaign_users';
$data['action'] = 'remove';
$data['campaign_id'] = '1234567890123456';
$data['users_list'] = 'user1,user2,user3,user4,user5';

Request Parameters

Parameter Name Example/Description Required
API 1.6 Yes
account_id Name of tenant Yes
type campaign_users Yes
action remove Yes
campaign_id 01234567890123456 Yes
users_list user1, user2, user3, etc Yes
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

Success XML Response

<response status="success">
  <users_removed>
    <user>user1</user>
    <user>user2</user>
    <user>user3</user>
    <user>user5</user>
  </users_removed>
</response>

Notes - Only the users that were actually removed that campaign's access permissions will be shown on the return XML. The following are reasons why a username is not returned: - The username is not valid, does not exist, or not associated with the account_id given. - The username already has permissions to access the campaign_id given. - The username is the owner id, which always has access to all campaigns.

Error XML Response:

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

Loyalty Programs

Campaign - New Campaign

Create New Campaign adds a new campaign to an existing account and returns the campaign_id of the new campaign.

The data to be submitted to the API is composed of the following fields that are common to all campaign types:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Create New Campaign Request

{$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';}

Create a New Points Based Campaign Request

{$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';}

Create a New Earned-Per-Event Campaign Request

{$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';}

Request Parameters

Name Description/Example Required
type campaign_new Yes
action campaign Yes
account_id Name of the Account, example: greatwidgets. Yes
campaign_type points
giftcard
events
earned
buyx		 Yes
campaign_name Name of the Campaign, example: Widget Rewards. Yes
latitude example:40.000001 Optional
longitude example:-40.000001 Optional
description example:Check-in at 3rd and 5th. Optional

Notes

If you are using PHP, the $data array would look like the following example for a Giftcard, Events, or BuyX Campaigns:

Additional Request Parameters for Points-Based Campaigns

Name Description/Example Value/Range
points_ratio example: 50 Required (see note)
reward_ratio example: 10 Optional (see note)

Note - 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 ability 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 Request Parameters for Earn-per-Event Campaigns

Name Description Value/Range
amount_per_event example: 4.95 Required (see note)

Note - 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

Name Description Value/Range
coalition_opt_out Y Optional or don't include.
two_tier_opt_out Y Optional or don't include.

A Earned-Per-Event Campaign Success XML Response

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

A Earned-Per-Event Campaign Error XML Response

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

Response Parameters

Name Description Value/Range
output JSON or XML Optional. If not provided, defaults to XML
callback Name of the function. Optional: JSON(P) format
condensed Yes or No Optional (No white space) Applies only to JSON(P) output

Campaign - New Reward

Add a new reward to an existing Points or Event-based campaign. The data to be submitted to the API is composed of the following fields.

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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

Create New Campaign Reward Request.

  $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';

Request Parameters

Name Example/Description Required
type campaign_new Yes
action reward Yes
account_id Name of tenant Yes
campaign_id ID of the Campaign, example: 1234567890123456 Yes
reward_level example: 1000 Yes
reward_description Free Widget Yes
reward_identifier example: 1010101 Optional
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

General 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 dependent 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 fulfillment 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.

Create New Campaign Reward Request 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.

Create New Campaign Reward Request Error XML Response:


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

Campaign - New Promotion

Add a new promotion to an existing Points-based campaign. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

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 equivalent 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 descriptive 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.

Create New Campaign Promotion Request Example PHP request if you are using PHP, the $data array would look like the following:


  $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%)';

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.

Request Parameters

Name Description/Example Required
type campaign_new Yes
action promo Yes
account_id Name of tenant. Yes
campaign_id Name of the campaign, example: 1234567890123456 Yes
promo_operation x or + Yes
promo_amount Example: 1.25 or 100 Yes
promo_description description of promo, example: Pre-booking bonus Yes
promo_custom_id Example: XFA-275 Optional
promo_start_date 2013-08-01
00:00:00		 Optional
promo_end_date 2013-08-15
23:59:59		 Optional
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

Create New Campaign Promotion Success XML Response

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

Create New Campaign Promotion Error XML Response

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

Campaign - New BuyX Item

Add a new item to an existing Buy X Get 1 Free campaign. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Create a New Buy X Campaign Request

{
  $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';
}

Request Parameters

Name Description/Example Required
type campaign_new Yes
action item Yes
account_id Name of the account. Example: greatwidgets Yes
campaign_id ID of the campaign. Example: 1234567890123456 Yes
reward_level Example: 10 Yes
item_description Description of the item(s). Example: Coffee or Tea Yes
item_identifier Example: 1DF34S1 Optional

Notes - The ability to create items is based on the permissions of the user_id 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.

If you are using PHP, the example request looks like the following $data array:

Create New Buy X Campaign Response 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.

Create New Buy X Campaign Response Error XML Response

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

Response Parameters

Name Description/Example Required
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

Campaign - New Deprecation

Create a new campaign depreciation in an existing account. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Create New Campaign Depreciation PHP Request If you are using PHP request, the $data array would look like this.

  $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';

Request Parameters

Name Example/Description Required
API 1.1 yes
type Depreciation_new Yes
action reward Yes
account_id Name of tenant Yes
campaign_id ID of the Campaign, example: 1234567890123456 Yes
depreciation_type per_transaction or last_transaction Yes
depreciation_interval 18 Yes
depreciation_interval_type days
months
years		 Yes
depreciation_percentage 100 Yes
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

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

Create New Campaign Depreciation 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>

Create New Campaign Depreciation Error XML Response

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

Campaign - New Fee

Create a new campaign fee in an existing account. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Create New Campaign Fee Request If you are using PHP request, the $data array would look like this.


  $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';

Request Parameters

Name Example/Description Required
type campaign_fee_new Yes
account_id Name of tenant Yes
campaign_id ID of the Campaign, example: 1234567890123456 Yes
fee_interval 18 Yes
Interval_type days
months
years		 Yes
fee_amount 100 points, or money depending on campaign type Optional
fee_description Service Charge. Yes
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

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

Create New Campaign Fee 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>

Create New Campaign Fee Error XML Response


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

Campaign - Update Campaign

Updates an existing campaign's basic settings. The data to be submitted to the API is composed of the following fields common to all campaign types:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

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

Points Based Campaign 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 ability 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 ability to redeem points by their currency value.

Earn-Per-Events Campaign 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.

Coalition and Two-Tier Campaign 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 coalition 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 Giftcard, Events, or BuyX Campaigns:

Update Campaign Request for Giftcard, Events, or BuyX Campaigns

$data['type'] = 'campaign_update';
$data['action'] = 'campaign';
$data['campaign_id'] = '1234567890123450';
$data['new_campaign_name'] = 'New Widget Card Name';

Update Campaign Request for a Points Campaign

$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';

Update Campaign Request for a Earned-per-Event Campaign

$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';

Request Parameters

Parameter Name Example/Description Required
type campaign_update Yes
action campaign Yes
account_id Name of tenant Yes
campaign_id ID of the Campaign, example: 1234567890123456 Yes
new_campaign_name New MyRewards Optional
new_points_ratio 100 Optional (See Points-Based Campaign Notes)
new_reward_ratio 18 Optional (See Points-Based Campaign Notes)
new_amount_per_event 5.95 Optional (See Earn-Per-Event Campaign Notes)
coalition_opt_out Y Optional (See Coalition and Two-Tier Campaign Notes)
two_tier_opt_out Y Optional ( See Coalition and Two-Tier Campaign Notes)
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

Update Campaign Response Success XML Response

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

Update Campaign Response Error XML Response

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

Campaign - Update Reward

Update an existing campaign reward to an existing Points or Event-based campaign. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

General 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 reward_level is an amount that is dependent 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 fulfillment 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.

Update Existing Campaign

Example PHP Requests

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

  $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';

Request Parameters

Name Example/Description Required
type campaign_update Yes
action reward Yes
account_id Name of tenant Yes
campaign_id ID of the Campaign, example: 1234567890123456 Yes
reward_id example: 57 Yes
new_reward_level example: 1000 Optional
new_reward_description example: Free Widget Optional
new_reward_identifier 1010101 Optional
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

Update Existing Campaign Response 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>

Campaign - Update Promotion

Update an existing promotion in a Points-based campaign. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Request: If you are using PHP for a request, the $data array would look like:

$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)';

Request Parameters

Parameter Name Example/Description Required
type campaign_update Yes
action promo Yes
account_id Name of tenant Yes
campaign_id 1234567890123456 Yes
promo_id 35 Yes
new_promo_operation x or + Optional
new_promo_amount 1.25 or 100 Optional
new_promo_description Pre-booking bonus Optional
new_promo_custom_id XFA-834 Optional
new_promo_start_date 2013-08-01
08:00:00		 Optional
new_promo_end_date 2013-08-31
23:59:59		 Optional
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

General 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 equivalent 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.

Success XML Response

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

Notes - 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>

Customers - Batch

Import one or more customers at a time. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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

$data['API'] = '1.5';
$data['account_id'] = 'greatwidgets';
$data['type'] = 'customers_batch';
$data['delimiter'] = 'pipe';
$data['overwrite_duplicates'] = 'update';
or: $data['card_number_generate'] = 10; // for 10-digit number.
$data['campaigns_to_include'] = '898989889|,|13234545|,|34534554';
$data['profiles_header_1'] = 'code';
$data['profiles_header_2'] = 'card_number';
$data['profiles_header_3'] = 'first_name';
$data['profiles_header_4'] = 'last_name';
$data['profiles_header_5'] = 'custome_date';
$data['profiles_header_6'] = 'phone';
$data['Profiles_Data'] = '
11223344|11223344|jane|doe|1970-07-14|555-5555
22334455|22334455|jim|mcdoe|1966-07-28|555-5556
33445566|33445566|larry|smith|1980-02-05|555-5557
';

Request Parameters

Name Example/Description Required
API 1.5 Yes
account_id Name of tenant Yes
type customers_batch Yes
delimiter pipe or comma or tab Yes
overwrite_duplicates yes or update or ignore See Note
allow_undo yes Optional: 'yes'
or don't include
card_number_generate (# of digits) Optional - See Note
campaigns_to_include 89898989989
or
aaaa, bbbb, cccc		 At least one is required.
If more than one, separate by comma.
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


Headers

Determines the order of the fields, separated by the delimiter, given in the data.

Parameter Name Example/Description Required/Note
profiles_header_1 card_number At least one is required, See Headers Notes
profiles_header_2 code (customer UID) At least one is required, See Headers Notes
profiles_header_3 first_name At least one is required, See Headers Notes
etc... Last_name
email
phone
custom_date
street1
street2
city
state
postal_code
country
customer_username
customer_password
customer_PIN
auto_add
custom_field_1
custom_field_2
custom_field_3
etc...		 At least one is required, See Headers Notes

Import Data

Parameter Name Example/Description Required/Note
profiles_data Data to be imported in batch:
One single (text) field with end-of-lines (ex: \n and/or \r) at the end of each line:
11223344/11223344/jane/doe/1970-07-14/555-5555
22334455/22334455/jim/mcdoe/966-07-28/555-5556
33445566/33445566/larry/smith/1980-02-05/555-5557

General Notes - Number the profiles_header_## fields in increasing order. Do not skip more than one! - You can change the order of the fields, just keep the profiles_header_## numbering from 1 to the number of fields you are using. - The difference in the settings for overwrite_duplicates is: - yes (overwrite): In case of a match, this option will blank out all existing fields/data for that customer, and replace with the data given. - update: In case of a match, this option will only change the fields that are given, leaving any customer fields that are not part of the import untouched. - ignore (skip): In case of a match, the existing data will be left untouched and the data row from the import data will be ignored. - no_undo: When set to yes, an undo state will not be recorded (ie: you can't undo the import). By default, if this parameter is not included, an undo state will be saved. When first importing, until you know that the data structure is consistently correct, do not include this parameter. Once the process is tested and automated, include and set the no-undo parameter to limit the list of undo states in the admin interface. - card_number_generate: When included, random card numbers will be generated (all numeric, of the given length) if a card_number is not included or is blank. - code' should be provided as the internal ID for the customer of the application that is sending the data. - If the application that is sending the data uses the 'card_number' as their unique Customer ID, then insert it as BOTH 'code' and 'card_number' entries. - If the application that is sending the data does not have an internal unique ID for a customer, do not include the 'code' entry. The API response will include our internally generated 16-digit unique id as part of the response to be recorded into your system to be transmitted back with all transactions associated with this customer. - If instead, you want the program to generate a random unique card number, then include the card_number_generate field with the number of digits for the card number to be generated. - The 'custom_date' must be in YYYY-MM-DD format. (Any other format cannot be resolved without further context. Ex: 04-03-2010 could be either April 3rd or 4th of March. Don't even get us started on inputs like 04-06-05... What the heck is THAT?) - The customer_username is an API-specific field made available for custom applications. It cannot be defined or edited in the web interface. - The customer_password field is made available for custom applications such as a customer hotsite. It can be defined or edited in the web interface. - The customer_PIN is an API-specific field made available for custom applications such as a physical terminal. It cannot be defined or edited in the web interface. - To automatically add an amount to the FIRST campaign specified above, use the optional auto_add parameter which lets you specify the amount of points, visits, dollars, or name of product or service, depending on the campaign type, to add. For example, as a thank-you bonus for signing-up, you would specify 25 as the data in the auto_add field for that customer (which will add 25 points to the customer's account balance.)

Headers Notes - Use the Customer Fields - List API call to determine the name (custom_field_##) of any added custom fields.


Success XML Response

<response status="success">
    <batch status="imported">
      <customers>
        <new>2<new>
        <updated>1<updated>
      <customers>
    </batch>
</response>

Error XML Response:

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

Campaign Update BuyX Item

Update an existing item in a Buy X Get 1 Free campaign. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Request: If you are using PHP for a request, the $data array would look like:

$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';

Request Parameters

Parameter Name Example/Description Required
type campaign_update Yes
action item Yes
account_id Name of tenant Yes
campaign_id 1234567890123456 Yes
item_id 234 Yes
new_reward_level 10 Optional
new_item_description Coffee or Tea Optional
new_item_identifier 1DF34S1 Optional
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

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

Success XML Response

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

Notes - 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>

Campaign - Update Depreciation

Update a campaign depreciation in an existing account. The data to be submitted to the API is composed of the following fields.

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Update Existing Campaign Depreciation Request

Example PHP Requests

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

  $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';

Request Parameters

Name Example/Description Required
API 1.1 Yes
type depreciation_update Yes
action Item Yes
account_id Name of tenant Yes
campaign_id ID of the Campaign, example: 1234567890123456 Yes
depreciation_id example: 346 Yes
depreciation_type example: per_transaction or last_transaction Optional
depreciation_interval example: 18 Optional
depreciation_interval_type example:
days
months
years		 Optional
depreciation_percentage example: 100 Optional
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

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

Update Existing Campaign Depreciation 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>e>

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

Update Existing Campaign Depreciation Error XML Response


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

Example PHP Requests If you are using PHP request, the $data array would look like this.

  $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';

Campaign - Update Fee

Update a campaign fee in an existing account. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Request: If you are using PHP for a request, the $data array would look like:

$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';

Request Parameters

Parameter Name Example/Description Required
type campaign_fee_update Yes
account_id Name of tenant Yes
campaign_id 1234567890123456 Yes
fee_id 567 Yes
fee_interval 18 Optional
interval_type days or
months or
years		 Optional
fee_amount 100 points or money depending on campaign type Optional
fee_description Service Charge Optional
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

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

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>

Campaign - List Campaigns

Returns a list of the campaigns for an account. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Notes There are 5 campaign types:

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

General 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 Requests

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

$data['API'] = '1.5';
$data['type'] = 'campaigns_list';
$data['account_id'] = 'greatwidgets';

Request Parameters

Name Example/Description Required
API 1.5 Yes
account_id Name of tenant Yes
type campaigns_list Yes
type_restrict points,
giftcard,
events,
earned,
buyx		 Optional
searchField campaign_name or campaign_type Optional
searchOper eq (equal)
ne (not equal)
bw (begins with)
bn (does not begin with)
ew (ends with)
en (does not end with)
cn (contains)
nc (does not contain)
nu (is null/empty)
nn (is not null/empty)
in (is in - comma-separated list)
ni (is not in - comma-separated list)		 Optional
searchValue Employee Optional
sortField campaign_name or campaign_type Optional
sortOrder DESC or ASC Optional
offset 0 Optional
length 10 Optional
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

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>

Example PHP Requests to list ONLY Gift Cards and Points campaigns If you are using PHP request, the $data array would look like:*

$data['API'] = '1.5';
$data['type'] = 'campaigns_list';
$data['account_id'] = 'greatwidgets';
$data['type_restrict'] = 'giftcard, points';

Successful XML Response for listing ONLY Gift Cards and Points campaigns.

<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 for listing ONLY Gift Cards and Points campaigns.


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

Campaign - List Deactivated

Returns a list of the deactivated campaigns for an account. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Request: If you are using PHP for a request, the $data array would look like:

$data['API'] = '1.5';
$data['type'] = 'campaigns_inactive_list';
$data['account_id'] = 'greatwidgets';

Request Parameters

Parameter Name Example/Description Required
API 1.5 Yes
account_id Name of tenant Yes
type campaigns_inactive_list Yes
type_restrict points,
giftcard,
events,
earned,
buyx		 Optional
searchField campaign_name or
campaign_type		 Optional
searchOper eq (equal)
ne (not equal)
bw (begins with)
bn (does not begin with)
ew (ends with)
en (does not end with)
cn (contains)
nc (does not contain)
nu (is null/empty)
nn (is not null/empty)
in (is in - comma-separated list)
ni (is not in - comma-separated list)		 Optional
searchValue London Optional
sortField campaign_name or
campaign_type		 Optional
sortOrder DESC or
ASC		 Optional
offset 0 Optional
length 10 Optional
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

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

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 for a request, the $data array would look like:

$data['API'] = '1.5';
$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 php Response:

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

Campaign - List Rewards

Returns a list of the rewards available for a given campaign. The data to be submitted to the API is composed of the following fields.

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Campaign Rewards List Example PHP Requests If you are using PHP request, the $data array would look like this.

$data['type'] = 'campaign_rewards';
$data['account_id'] = 'greatwidgets';
$data['campaign_id'] = '1111222233334444';

Request Parameters

Name Example/Description Required
type campaign_rewards Yes
account_id Name of tenant Yes
campaign_id 1111222233334444 Yes
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

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

Campaign Rewards List 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.

Campaign Rewards List Error XML Response.


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

Campaign - List Promotions

Returns a list of the promotions available for a given campaigns.

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Campaign Promotions List Example PHP Request

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

$data['API'] = '1.5';
$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';

Request Parameters

Name Example/Description Required
API 1.5 Yes
account_id Name of tenant Yes
type campaign_promos Yes
campaign_id 1111222233334444 Yes
searchField promotion
operation
multiplier		 Optional
searchOper eq (equal)
ne (not equal)
bw (begins with)
bn (does not begin with)
ew (ends with)
en (does not end with)
cn (contains)
nc (does not contain)
nu (is null/empty)
nn (is not null/empty)
in (is in - comma-separated list)
ni (is not in - comma-separated list)		 Optional
searchValue Double (promotion) or
x (operation) or
2 (multiplier)		 Optional
sortField promotion or
operation
multiplier		 Optional
sortOrder DESC or ASC Optional
offset 0 Optional
length 10 Optional
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

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

Campaign Promotions List 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.

Campaign Promotions List No Promos XML Response


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

Campaign Promotions List Error XML Response


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

Campaign - List Depreciations

Returns a list of the depreciations for a given campaign. The data to be submitted to the API is composed of the following fields.

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Campaign Depreciations List Example PHP Request If you are using PHP request, the $data array would look like this.

  $data['type'] = 'campaign_depreciations';
  $data['account_id'] = 'greatwidgets';
  $data['campaign_id'] = '1234567890123456';

Request Parameters

Name Example/Description Required
type campaign_depreciations Yes
account_id Name of tenant Yes
campaign_id 1234567890123456 Yes
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

General Notes

Campaign Depreciations List Example

PHP 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. Campaign Depreciations List Example PHP Error XML Response.

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

Campaign - List Fees

Returns a list of the fees for a given campaign. The data to be submitted to the API is composed of the following fields.

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Campaign Fees List Example PHP Requests If you are using PHP request, the $data array would look like this.

  $data['type'] = 'campaign_fees';
  $data['account_id'] = 'greatwidgets';
  $data['campaign_id'] = '1234567890123456';

Campaign Fees List Request Parameters

Name Example/Description Required
type campaign_fees Yes
account_id Name of tenant Yes
campaign_id 1234567890123456 Yes
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

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

Campaign Fees List 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.

Campaign Fees List Error XML Response

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

Campaign - Delete Campaign

Removes a campaign from an account, including all customer transactions in it. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests If you are using PHP request, the $data array would look like:

  $data['type'] = 'campaign_delete';
  $data['action'] = 'campaign';
  $data['account_id'] = 'greatwidgets';
  $data['campaign_id'] = '1234567890123456';

Request Parameters

Name Example/Description Required
type campaign_delete Yes
action campaign Yes
account_id Name of tenant Yes
campaign_id 1234567890123456 Yes
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

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

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>

Campaign - Delete Reward

Removes a reward from an account campaign. The data submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests If you are using PHP request, the $data array would look like:

  $data['type'] = 'campaign_delete';
  $data['action'] = 'reward';
  $data['account_id'] = 'greatwidgets';
  $data['campaign_id'] = '1234567890123456';
  $data['reward_id'] = '432';

Request Parameters

Parameter Name Example/Description Required
type campaign_delete Yes
action reward Yes
account_id Name of tenant Yes
campaign_id 1234567890123456 Yes
reward_id 432 Yes
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

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

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>

Campaign - Delete Promo

Removes a promotion from an account's campaign. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Request Parameters

Name Example/Description Required
type campaign_delete Yes
action promo Yes
account_id Name of tenant Yes
campaign_id 1234567890123456 Yes
promo_id 543 Yes
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

General 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 Requests If you are using PHP request, the $data array would look like:

  $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>SS-Loyalty-Campaign-DeleteAPromotion.md
  </response>

Error XML Response:

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

Campaign - Delete BuyX Item

Removes an item from an existing Buy X Get 1 Free campaign. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Request: If you are using PHP for a request, the $data array would look like:

$data['type'] = 'campaign_delete';
$data['action'] = 'item';
$data['account_id'] = 'greatwidgets';
$data['campaign_id'] = '1234567890123456';
$data['item_id'] = '678';

Request Parameters

Parameter Name Example/Description Required
type campaign_delete Yes
action item Yes
account_id Name of tenant Yes
campaign_id 1234567890123456 Yes
item_id 678 Yes
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

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

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>

Campaign - Delete Depreciation

Removes a campaign depreciation entry from an account's campaign. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName} 
  $data['type'] = 'depreciation_delete';
  $data['account_id'] = 'greatwidgets';
  $data['campaign_id'] = '1234567890123456';
  $data['fee_id'] = '456';

Request Parameters

Name Example/Description Required
type depreciation_delete Yes
account_id Name of tenant Yes
campaign_id 1234567890123456 Yes
depreciation_id 456 Yes
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

General 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 Requests If you are using PHP request, the $data array would look like: 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>

Campaign - Delete Fee

Removes a campaign fee entry from an account's campaign. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Request Parameters

Name Example/Description Required
type campaign_fee_delete Yes
account_id Name of tenant Yes
campaign_id 1234567890123456 Yes
fee_id 456 Yes
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

General 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 Requests If you are using PHP request, the $data array would look like:

  $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>

Campaign - Deactivate

A safer and reversible alternative to deleting a campaign.

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

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests If you are using PHP request, the $data array would look like:

  $data['type'] = 'campaign_deactivate';
  $data['account_id'] = 'greatwidgets';
  $data['campaign_id'] = '1234567890123456';

Request Parameters

Parameter Name Example/Description Required
type campaign_deactivate Yes
account_id Name of tenant Yes
campaign_id 1234567890123456 Yes
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

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

Success XML Response

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

Error XML Response:

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

Campaign - Reactivate

Makes a campaign that has been previously deactivated active again. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Campaign Rewards List Example PHP Requests If you are using PHP request, the $data array would look like this.

  $data['type'] = 'campaign_reactivate';
  $data['account_id'] = 'greatwidgets';
  $data['campaign_id'] = '1234567890123456';

Request Parameters

Name Example/Description Required
type campaign_reactivate Yes
account_id Name of tenant Yes
campaign_id 1234567890123456 Yes
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

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

Campaign Rewards List Success XML Response

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

Campaign Rewards List Error XML Response

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

Customers

Customer - New / Register

Create a customer account; Returns a unique Account ID.

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

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests If you are using PHP for a request, the $data array would look like:

  $data['type'] = 'record_customer';
  $data['customer_action'] = 'new';
  $data['account_id'] = 'greatwidgets';
  $data['campaign_id'] = '1234567890123456';
  $data['card_number']  = '1212121212';
  or: $data['card_number_generate'] = 10; // for 10-digit number.
  $data['code'] = '89898989898989';
  $data['first_name']   = 'John';
  $data['last_name']    = 'Doe';
  $data['phone']    = '555-555-2455';
  $data['email']    = 'test@yourdomain.com';
  $data['custom_date']  = '1970-07-14';
  $data['street1']  = '123 Main St.';
  $data['street2']  = 'Apt 3G';
  $data['city'] = 'Anytown';
  $data['state']    = 'ZZ';
  $data['postal_code'] = '55555';
  $data['country']  = 'New Zealand';
  $data['custom_field'] = 'John likes cheese.';
  $data['customer_username'] = 'jdoe1970';
  $data['customer_password'] = 'ilovecheese';
  $data['customer_PIN'] = '1234';
  $data['custom_field_2'] = 'Single';

Request Parameters

Parameter Name Example/Description Required
type record_customer Yes
customer_action new or register Yes
account_id Name of tenant Yes
campaign_id 1234567890123456
or
12344234,1234234,1234124		 Optional
card_number 1212121212 Optional
card_number_generate (# of digits) Optional
code 89898989898989 Optional
new_code Yes Optional
first_name John Optional
last_name Doe Optional
phone 555-555-2455 Optional
email test@email.com Optional
street1 123 Main St. Optional
street2 Apt 3G Optional
city Anytown Optional
state ZZ Optional
postal_code 55555 Optional
country New Zealand Optional
custom_date 1970-07-14 Optional
custom_field John likes cheese. Optional
customer_username jdoe1970 Optional
customer_password ilovecheese Optional
customer_PIN 1234 Optional
custom_field_## 1kg Emental Cheese
or
2012.07.28 22:59:59
or
Gouda,Emental,Swiss		 Optional
cuto_add 1500 Optional
send_no_email true Optional
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

General Notes - code should be provided as the internal ID for the customer of the application that is sending the data. - If the application that is sending the data uses the card_number as their unique Customer ID, then insert it as BOTH code and card_number entries. - If the application that is sending the data does not have an internal unique ID for a customer, do not include the code entry: - If this is a customer_action = new call, the card_number will be used as the code and that's what will be returned in the API response. If you don't want that to happen, then include the code_new parameter set to Yes to force the generation of a 16-digit UID. - In either case, if your application can, record the code transmitted back, and include it with all transactions associated with this customer. If not, don't worry. You can always query the API for the code associated with a card_number for future transactions recording. - If you want the program to generate a random unique card number, then include the card_number_generate field with the number of digits for the card number to be generated. - All optional fields are optional individually, but at least ONE must be passed along. - If the customer_action tag is set to new and a customer record is sent that matches an existing record, an error will be generated. - If the customer_action tag is set to register, the card_number field must match an existing record in the database, and the customer_password field must not have been previously set (in the database). If both these conditions are true, and both a card_number and valid customer_password are given, then the user information is recorded and the status returned will be registered. Otherwise, an error message will be returned saying that the card has already been registered. - The campaign_id is optional, can be provided either singly or as a comma separated list. - If not given, a customer will be recorded into the system, but won't belong to any campaign (until a transaction is added for that customer to a campaign) - If only a single campaign ID is provided, the customer will be recorded and an Activation transaction recorded in the given campaign. - If a list of campaign_ids is given, then an activation transaction will be recorded for each campaign in the list. - Notes: - Activation transactions do not affect campaign balances. - A customer belongs to a campaign when they have any sort of transaction in that campaign. - The custom_date must be in YYYY-MM-DD format. (Any other format cannot be resolved without further context. Ex: 04-03-2010 could be either April 3rd or 4th of March. Don't even get us started on inputs like 04-06-05... What the heck is THAT?. Also this format conforms to ISO-8601.) - The customer_username is an API-specific field made available for custom applications. It cannot be defined or edited in the web interface. - The customer_password field is made available for custom applications such as a customer hotsite. It can be defined or edited in the web interface. - The customer_PIN is an API-specific field made available for custom applications such as a physical terminal. It cannot be defined or edited in the web interface. - To automatically add an amount to a customer's account in the campaign specified above, when using this call, the optional auto_add parameter lets you specify the amount of points, visits, dollars, or name of product or service, depending on the campaign type, to add. For example, as a thank-you bonus for signing-up, you would user auto_add = 25 (which will add 25 points to the customer's account balance.) - The send_no_email is an API-specific field that if included will suppress the normal email that is generated and sent to the account owner letting them know about the new customer and their information (for example to send a plastic card to.) - custom_field_## must be first defined by through the Custom Fields - Create API call, and can be listed by first calling the Custom Fields - List API call. The content of a custom field must match its type. So for example, if a custom field expects a date / time stamp, it will reject with an error anything but that format.

Success XML Response (New Customer)

  <response status="success">
    <customer status="new">
      <code>1234567890123456</code>
      //only when card_number_generate is set:
      <card_number>1234567890</card_number>
    </customer>
  </response>

Error XML Response:

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

Customer - Update

Update a customer account with new information.

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

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests If you are using PHP request, the $data array would look like:

$data['type'] = 'record_customer';
$data['customer_action'] = 'edit';
$data['account_id'] = 'greatwidgets';
$data['code']   = '89898989898989';
$data['card_number']    = '1212121212';
or: $data['card_number_generate'] = 10; // for 10-digit number.
$data['first_name'] = 'John';
$data['last_name']  = 'Doe';
$data['phone']  = '555-555-2455';
$data['email']  = 'test@yourdomain.com';
$data['custom_date']    = '1970-07-14';
$data['street1']    = '123 Main St.';
$data['street2']    = 'Apt 3G';
$data['city']   = 'Anytown';
$data['state']  = 'ZZ';
$data['postal_code'] = '55555';
$data['country']    = 'New Zealand';
$data['customer_username'] = 'jdoe1970';
$data['customer_password'] = 'ilovecheese';
$data['customer_PIN'] = '1234';
$data['custom_field_2'] = 'Single';

Request Parameters

Parameter Name Example/Description Required
type record_customer Yes
customer_action edit Yes
account_id Name of tenant Yes
code 89898989898989 Optional
new_code yes Optional
card_number 1212121212 Optional
card_number_generate (# of digits) Optional
first_name John Optional
last_name Doe Optional
phone 555-555-2455 Optional
email test@email.com Optional
street1 123 Main St. Optional
street2 Apt 3G Optional
city Anytown Optional
state ZZ Optional
postal_code 55555 Optional
country New Zealand Optional
custom_date 1970-07-14 Optional
custom_field John likes cheese. Optional
customer_username jdoe1970 Optional
customer_password ilovecheese Optional
customer_PIN 1234 Optional
custom_field_## 1kg Emental Cheese
or
2012.07.28 22:59:59
or
Gouda,Emental,Swiss		 Optional
send_no_email true Optional
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

General Notes - 'code' is required to update an EXISTING customer as it is the internal ID for the customer. - If it is NOT included, a NEW customer will be created, and the API response will return a randomly generated 16-digit unique id as the 'code'. - If the code is given, but it matches NO existing customer, a NEW customer will be created with the information given. - In either case, if your application can, record the 'code' transmitted back, and include it with all transactions associated with this customer. If not, don't worry. You can always query the API for the 'code' associated with a card_number for future transactions recording. - If only a card_number is passed on an edit call, it will first try to match it to an existing card_number. If there's multiple matches, it will return an error. If there's a single match, it will assume that record to be the correct one, and proceed with the edit, and return the pre-existing code of the record that was matched and modified. If no matching card_number is found, it will attempt one last match at the code, and if it finds a single code that matches the card_number, then it will update that record and return that code. (In both cases, edit also means that whatever card_number existed will be replaced by the one used in this API call.) If there's no match, as mentioned above, it will create a new record and return a random 16-digit code. - If you want the program to generate a random unique card number, then include the card_number_generate field with the number of digits for the card number to be generated. - All optional fields are optional individually, but at least ONE must be passed along. - If the customer_action tag is set to edit, and the customer data matches an existing record, the existing record will be updated with the new information and a status of update will be returned in the response. If instead, no match is found, a new customer will be created with the information passed, and the status returned will be new. - The 'custom_date' must be in YYYY-MM-DD format. (Any other format cannot be resolved without further context. Ex: 04-03-2010 could be either April 3rd or 4th of March. Don't even get us started on inputs like 04-06-05... What the heck is THAT?. Also this format conforms to ISO-8601.) - The customer_username is an API-specific field made available for custom applications. It cannot be defined or edited in the web interface. - The customer_password field is made available for custom applications such as a customer hotsite. It can be defined or edited in the web interface. - The customer_PIN is an API-specific field made available for custom applications such as a physical terminal. It cannot be defined or edited in the web interface. - To automatically add an amount to a customer's account in the campaign specified above, when using this call, the optional auto_add parameter lets you specify the amount of points, visits, dollars, or name of product or service, depending on the campaign type, to add. For example, as a thank-you bonus for signing-up, you would user auto_add = 25 (which will add 25 points to the customer's account balance.) - The send_no_email is an API-specific field that if included will suppress the normal email that is generated and sent to the account owner letting them know about the new customer and their information (for example to send a plastic card to.) - custom_field_## must be first defined by through the Custom Fields - Create API call, and can be listed by first calling the Custom Fields - List API call. The content of a custom field must match its type. So for example, if a custom field expects a date / time stamp, it will reject with an error anything but that format.

Success XML Response (Update Customer)

  <response status="success">
    <customer status="update">
      <code>1234567890123456</code>
      //only when card_number_generate is set:
      <card_number>1234567890</card_number>
    </customer>
  </response>

Error XML Response:

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

Customer - Generate Card

Creates a random card number of a given length and checks that this number is unique and not in use already in the account. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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

$data['account_id'] = 'greatwidgets';
$data['type'] = 'generate_card_number';
or: $data['how_many_digits'] = 10; // for 10-digit number.

Request Parameters

Parameter Name Example/Description Required
account_id Name of tenant Yes
type generate_card_number Yes
how_many_digits (# of digits) Optional
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

General Notes - The how_many_digits parameter is optional: if it is not given, it will default to 16 digits.

Success XML Response

  <response status="success">
    <customer>
      <card_number>1234567890</card_number>
    </customer>
  </response>

Error XML Response

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

Customer - Batch

Import one or more customers at a time. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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

$data['API'] = '1.5';
$data['account_id'] = 'greatwidgets';
$data['type'] = 'customers_batch';
$data['delimiter'] = 'pipe';
$data['overwrite_duplicates'] = 'update';
or: $data['card_number_generate'] = 10; // for 10-digit number.
$data['campaigns_to_include'] = '898989889|,|13234545|,|34534554';
$data['profiles_header_1'] = 'code';
$data['profiles_header_2'] = 'card_number';
$data['profiles_header_3'] = 'first_name';
$data['profiles_header_4'] = 'last_name';
$data['profiles_header_5'] = 'custome_date';
$data['profiles_header_6'] = 'phone';
$data['Profiles_Data'] = '
11223344|11223344|jane|doe|1970-07-14|555-5555
22334455|22334455|jim|mcdoe|1966-07-28|555-5556
33445566|33445566|larry|smith|1980-02-05|555-5557
';

Request Parameters

Parameter Name Example/Description Required
API 1.5 Yes
account_id Name of tenant Yes
type customers_batch Yes
delimiter pipe or comma or tab Yes
overwrite_duplicates yes or update or ignore See Note
allow_undo yes Optional: 'yes'
or don't include
card_number_generate (# of digits) Optional - See Note
campaigns_to_include 89898989989
or
aaaa, bbbb, cccc		 At least one is required.
If more than one, separate by comma.
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

Headers

Determines the order of the fields, separated by the delimiter, given in the data.

Parameter Name Example/Description Required/Note
profiles_header_1 card_number At least one is required, See Headers Notes
profiles_header_2 code (customer UID) At least one is required, See Headers Notes
profiles_header_3 first_name At least one is required, See Headers Notes
etc... Last_name
email
phone
custom_date
street1
street2
city
state
postal_code
country
customer_username
customer_password
customer_PIN
auto_add
custom_field_1
custom_field_2
custom_field_3
etc...		 At least one is required, See Headers Notes

Import Data

Parameter Name Example/Description Required/Note
profiles_data Data to be imported in batch:
One single (text) field with end-of-lines (ex: \n and/or \r) at the end of each line:
11223344/11223344/jane/doe/1970-07-14/555-5555
22334455/22334455/jim/mcdoe/966-07-28/555-5556
33445566/33445566/larry/smith/1980-02-05/555-5557

General Notes - Number the profiles_header_## fields in increasing order. Do not skip more than one! - You can change the order of the fields, just keep the profiles_header_## numbering from 1 to the number of fields you are using. - The difference in the settings for overwrite_duplicates is: - yes (overwrite): In case of a match, this option will blank out all existing fields/data for that customer, and replace with the data given. - update: In case of a match, this option will only change the fields that are given, leaving any customer fields that are not part of the import untouched. - ignore (skip): In case of a match, the existing data will be left untouched and the data row from the import data will be ignored. - no_undo: When set to yes, an undo state will not be recorded (ie: you can't undo the import). By default, if this parameter is not included, an undo state will be saved. When first importing, until you know that the data structure is consistently correct, do not include this parameter. Once the process is tested and automated, include and set the no-undo parameter to limit the list of undo states in the admin interface. - card_number_generate: When included, random card numbers will be generated (all numeric, of the given length) if a card_number is not included or is blank. - code' should be provided as the internal ID for the customer of the application that is sending the data. - If the application that is sending the data uses the 'card_number' as their unique Customer ID, then insert it as BOTH 'code' and 'card_number' entries. - If the application that is sending the data does not have an internal unique ID for a customer, do not include the 'code' entry. The API response will include our internally generated 16-digit unique id as part of the response to be recorded into your system to be transmitted back with all transactions associated with this customer. - If instead, you want the program to generate a random unique card number, then include the card_number_generate field with the number of digits for the card number to be generated. - The 'custom_date' must be in YYYY-MM-DD format. (Any other format cannot be resolved without further context. Ex: 04-03-2010 could be either April 3rd or 4th of March. Don't even get us started on inputs like 04-06-05... What the heck is THAT?) - The customer_username is an API-specific field made available for custom applications. It cannot be defined or edited in the web interface. - The customer_password field is made available for custom applications such as a customer hotsite. It can be defined or edited in the web interface. - The customer_PIN is an API-specific field made available for custom applications such as a physical terminal. It cannot be defined or edited in the web interface. - To automatically add an amount to the FIRST campaign specified above, use the optional auto_add parameter which lets you specify the amount of points, visits, dollars, or name of product or service, depending on the campaign type, to add. For example, as a thank-you bonus for signing-up, you would specify 25 as the data in the auto_add field for that customer (which will add 25 points to the customer's account balance.)

Headers Notes - Use the Customer Fields - List API call to determine the name (custom_field_##) of any added custom fields.

Success XML Response


<response status="success">
    <batch status="imported">
      <customers>
        <new>2<new>
        <updated>1<updated>
      <customers>
    </batch>
</response>

Error XML Response:


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

Search for a customer within each given field. As opposed to Customer - Find, which finds a customer across all fields.

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

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Request Parameters

Name Example/Description Required
type customer_search Yes
exact_match sensitive or insensitive Do not include for partial matching.
account_id Name of tenant Yes
card_number 1234 Optional
first_name John Optional
last_name Doe Optional
phone 555-5555 Optional
email jdoe@gmail.com Optional
city Anytown Optional
state ONT Optional
postal_code 55555 Optional
custom_date 1970-07-14 Optional
custom_field baltimore Optional
customer_username jdoe1970 Optional
customer_password pa$$w0rd Optional
customer_PIN 1234 Optional
custom_field_# Married Optional
include_balances Y Do not include if not wanted.
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

General Notes - At least one of the optional fields must be provided, otherwise, the whole customer list will be returned. - If multiple matches result, then a list of those matching customers will be returned, with each customer's information. - The custom_date field must be given in YYYY-MM-DD format. - Text-based matches are not case-sensitive. - The search will return partial matches. For example: Searching for the first name John will return any record whose first name is also Johnny. Searching for a partial card number will return all the customers whose card number includes the segment given. - If the exact_match parameter is not included, the search will include partial matches and be case-insensitive (ex: searching for smith will also return Smithson or O'Smithy.) - If the exact_match parameter is included, using sensitive will match capitalization (ex: searching for smith will not return Smith) and will not include partial matches. - If the exact_match parameter is included, using insensitive will include any capitalization (ex: searching for smith will return Smith) but will not include partial matches.

Example PHP Requests

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

$data['type'] = 'customer_search';
$data['account_id'] = 'greatwidgets';
$data['last_name'] = 'Doe';
$data['phone'] = 555-5555;

Success XML Response with single match

<response status="success">
  <customer>
    <code>89898989898989</code>
    <card_number>1212121212</card_number>
    <first_name>John</first_name>
    <last_name>Doe</last_name>
    <phone>555-5555</phone>
    <email>john@email.com</email>
    <street1>123 Main St.</street1>
    <street2>Apt 3G</street2>
    <city>Anytown</city>
    <state>ONT</state>
    <postal_code>55555</postal_code>
    <country>New Zealand</country>
    <custom_date>1970-07-14</custom_date>
    <custom_field>He Likes Cheese</custom_field>
    <customer_username>jdoe1970</customer_username>
  </customer>
</response>

Success XML Response with multiple matches

<response status="success">
  <customer>
    <code>89898989898989</code>
    <card_number>1212121212</card_number>
    <first_name>John</first_name>
    <last_name>Doe</last_name>
    <phone>555-5555</phone>
    <email>john@email.com</email>
    <street1>123 Main St.</street1>
    <street2>Apt 3G</street2>
    <city>Anytown</city>
    <state>ONT</state>
    <postal_code>55555</postal_code>
    <country>New Zealand</country>
    <custom_date>1970-07-14</custom_date>
    <custom_field>He Likes Cheese</custom_field>
    <customer_username>jdoe1970</customer_username>
  </customer>
  <customer>
    <code>1234567890123456</code>
    <card_number>1313131313</card_number>
    <first_name>Jane</first_name>
    <last_name>Smith</last_name>
    <phone>555-6666</phone>
    <email>j.smith@workemail.com</email>
    <street1>321 Side St.</street1>
    <street2></street2>
    <city>Bigtown</city>
    <state>CA</state>
    <postal_code>55555</postal_code>
    <country></country>
    <custom_date>1966-07-28</custom_date>
    <custom_field></custom_field>
    <customer_username>janesmith222</customer_username>
  </customer>
</response>

Success XML Response with include_balances = Y

 <response status="success">
   <customer>
     <code>89898989898989</code>
     <card_number>1212121212</card_number>
     <first_name>John</first_name>
     <last_name>Doe</last_name>
     <phone>555-5555</phone>
     <email>john@email.com</email>
     <street1>123 Main St.</street1>
     <street2>Apt 3G</street2>
     <city>Anytown</city>
     <state>ONT</state>
     <postal_code>55555</postal_code>
     <country>New Zealand</country>
     <custom_date>1970-07-14</custom_date>
     <custom_field>He Likes Cheese</custom_field>
     <customer_username>jdoe1970</customer_username>
     <campaigns>
       <campaign>
         <id>1234567890123456</id>
         <name>Widget Rewards</name>
         <type>points</type>
         <balance>1500</balance>
         <cumulative>4750</cumulative>
         <last_transaction>2011-12-31</last_transaction>
       </campaign>
       ...
     </campaigns>
   </customer>
   ...
</response>

Error XML Response if no customer matches fields given

  <response status="no_match">
    <message>Language-specific "No Customers Match Criteria"</message>
  </response>

Error XML Response

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

Customer - Find

Finds a customer across all fields as opposed to Customer Search which searches only inside each given fields.

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

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
Api-Key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Examples PHP Requests

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

$data['type'] = 'customer_find';
$data['account_id'] = 'greatwidgets';
$data['find_customer'] = 'Amy Acker, 1234 Main St';

Request Parameters

Parameter Name Example/Description Required
type customer_find Yes
account_id Name of tenant Yes
find_customer Amy Acker, 1234
Main St		 Yes
include_balances Y Optional
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

General Notes

Success XML Response with single match:

  <response status="success">
    <customer>
      <code>89898989898989</code>
      <card_number>1212121212</card_number>
      <first_name>Amy</first_name>
      <last_name>Doe</last_name>
      <phone>555-5555</phone>
      <email>adoe@email.com</email>
      <street1>123 Acker St.</street1>
      <street2>Apt 3G</street2>
      <city>Anytown</city>
      <state>ONT</state>
      <postal_code>55555</postal_code>
      <country>New Zealand</country>
      <custom_date>1970-07-14</custom_date>
      <custom_field>She Likes Cheese</custom_field>
      <customer_username>adoe1970</customer_username>
    </customer>
  </response>

Success XML Response with multiple matches:

  <response status="success">
    <customer>
      <code>1234567890123456</code>
      <card_number>1313131313</card_number>
      <first_name>John</first_name>
      <last_name>Doe</last_name>
      <phone>555-1234</phone>
      <email>john@email.com</email>
      <street1>434 Great St.</street1>
      <street2></street2>
      <city>Maintown</city>
      <state>ONT</state>
      <postal_code>55555</postal_code>
      <country>New Zealand</country>
      <custom_date>1966-07-28</custom_date>
      <custom_field></custom_field>
      <customer_username>jdoe1966</customer_username>
    </customer>
    <customer>
      <code>89898989898989</code>
      <card_number>1212121212</card_number>
      <first_name>Amy</first_name>
      <last_name>Doe</last_name>
      <phone>555-5555</phone>
      <email>adoe@email.com</email>
      <street1>123 Acker St.</street1>
      <street2>Apt 3G</street2>
      <city>Anytown</city>
      <state>ONT</state>
      <postal_code>M5A-5A5</postal_code>
      <country></country>
      <custom_date>1970-07-14</custom_date>
      <custom_field>She Likes Cheese</custom_field>
      <customer_username>adoe1970</customer_username>
    </customer>
  </response>

Success XML Response with with include_balances = Y:

  <response status="success">
    <customer>
      <code>89898989898989</code>
      <card_number>1212121212</card_number>
      <first_name>John</first_name>
      <last_name>Doe</last_name>
      <phone>555-1234</phone>
      <email>john@email.com</email>
      <street1>434 Great St.</street1>
      <street2></street2>
      <city>Maintown</city>
      <state>ONT</state>
      <postal_code>55555</postal_code>
      <country>New Zealand</country>
      <custom_date>1966-07-28</custom_date>
      <custom_field></custom_field>
      <customer_username>jdoe1966</customer_username>
      <campaigns>
        <campaign>
          <id>1234567890123456</id>
          <name>Widget Rewards</name>
          <type>points</type>
          <balance>1500</balance>
          <cumulative>4750</cumulative>
          <last_transaction>2011-12-31</last_transaction>
        </campaign>
        ...
      </campaigns>
    </customer>
    ...
  </response>

XML Response if no customer matches fields given:

  <response status="no_match">
    <message>Language-specific `No Customers Match Criteria`</message>
  </response>

Error XML Response:

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

Customer - Information

Retrieves a customer's information and campaigns' balances.

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

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Request: If you are using PHP for a request, the $data array would look like:

$data['type'] = 'customer_info';
$data['account_id'] = 'greatwidgets';
$data['code'] = '89898989898989';
or: $data['card_number'] = 1212121212;

Request Parameters

Parameter Name Example/Description Required
type customer_info Yes
account_id Name of tenant Yes
include_balances N Optional
campaign_id 12345667890123456 Optional
hide_custom_field Y Optional
card_number 1212121212 See Notes
code 89898989898989 See Notes
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

General Notes - Either 'code' or 'card_number' must be passed. - If the parameter 'hide_custom_field' is not given, the custom_field (custom1) will be returned. There is no need to pass on a value equivalent to hide_custom_field = N. - For coalition accounts, the balance for each campaign will be the coalition balance, not the individual campaign balance. Hence the totals of the transactions for each campaign may not add up to the coalition balance, since the customer may have multiple transactions in multiple campaign(s). - All fields are returned on this call, even if they have been turned off in the web interface. This is to allow different interfaces to show / access different fields, and thus to allow maximum customization by you. - To restrict the return XML to JUST the customer info, and not include campaign balances and rewards available per customer, add the include_balances parameter set to N. - To instead restrict the return XML to just a single campaign's balance and available rewards, add the campaign_id parameter.

Success XML Response

  <response status="success">
    <customer>
      <code>89898989898989</code>
      <card_number>1212121212</card_number>
      <first_name>John</first_name>
      <last_name>Doe</last_name>
      <phone>555-5555</phone>
      <email>john@email.com</email>
      <street1>123 Main St.</street1>
      <street2>Apt 3G</street2>
      <city>Anytown</city>
      <state>ONT</state>
      <postal_code>55555</postal_code>
      <country>New Zealand</country>
      <custom_date>1970-07-14</custom_date>
      <custom_field>He Likes Cheese</custom_field>
      <customer_username>jdoe1970</customer_username>
      <registered>Y</registered>
      <custom_field_2>
        <label>Marital Status</label>
        <data>Single</data>
      </custom_field_2>
      ...
    </customer>
    <campaigns>
      <campaign>
        <id>1234567890123456</id>
        <name>Widget Rewards</name>
        <type>points</type>
        <balance>1500</balance>
        <cumulative>4500</cumulative>
        <monetary_balance>10.00</monetary_balance>
        <currency>EUR</currency>
        <glyph>€</glyph>
        <last_transaction>2011-12-31</last_transaction>
        <available_rewards>
          <reward>
            <id>678</id>
            <description>Free Widget</description>
            <needed_to_redeem>1000</needed_to_redeem>
            <reward_id>A-345678</reward_id>
          </reward>
          <reward>
            <id>753</id>
            <description>Free bigger widget</description>
            <needed_to_redeem>2500</needed_to_redeem>
          </reward>
        </available_rewards>
      </campaign>
      <campaign>
        <id>2345678901234567</id>
        <name>Employee Rewards</name>
        <type>earned</type>
        <balance>16.50</balance>
        <currency>EUR</currency>
        <cumulative>59.95</cumulative>
        <last_transaction>2011-12-31</last_transaction>
      </campaign>
      <campaign>
        <id>3456789012345678</id>
        <name>Frequent Buyer</name>
        <type>buyx</type>
        <balances>
          <item>
            <name>Coffees</name>
            <item_id>96</item_id>
            <balance>14</balance>
            <earned>1</earned>
            <cumulative>24</cumulative>
            <redeemed>1</redeemed>
            <earn_ratio>10</earn_ratio>
          </item>
          <item>
            <name>Cakes</name>
            <item_id>107</item_id>
            <balance>11</balance>
            <earned>1</earned>
            <cumulative>21</cumulative>
            <redeemed>1</redeemed>
            <earn_ratio>10</earn_ratio>
          </item>
          <item>
            <name>Books</name>
            <balance>2</balance>
            <earned>0</earned>
            <cumulative>2</cumulative>
            <redeemed>0</redeemed>
            <earn_ratio>5</earn_ratio>
          </item>
        </balances>
        <last_transaction>2011-12-31</last_transaction>
        <available_rewards>
          <reward>
            <item_id>96</item_id>
            <name>Coffees</name>
            <earn_ratio>10</earn_ratio>
            <reward_id>A-345678</reward_id>
          </reward>
          <reward>
            <item_id>107</item_id>
            <name>Cakes</name>
            <earn_ratio>10</earn_ratio>
          </reward>
        </available_rewards>
      </campaign>
    </campaigns>
  </response>

Notes - The registered tag is returned as 'Y' is the customer has a password defined in their record. - For BuyX Campaigns: - The balance is the amount of purchases that have accumulated and that count towards earning a free item. - The earned is the amount of items that the customer has earned based on the balance of items purchased. - The cumulative balance is the number of purchases by the customer over their lifetime participating in the campaign. This includes purchases that counted towards a redemption. - The redeemed balance is the number of free items that the customer has gotten over their lifetime participation in the campaign. - When an earned item is redeemed, the amount of items that were needed to earn it are deducted from the balance and the redeemed balance is incremented by 1. - For example: A campaign allows customers to earn 1 free coffee per 10 purchased (this ratio is defined when a campaign is created or updated and is also reported in the Campaign - List BuyX Items API call for ALL the items, as well as in the available_rewards for the items that the customer has earned at least one of.) Now imagine that a customer purchases 14 coffees over a few days. This this means that they have: - A balance of 14 - earned 1 free Coffee - A lifetime cumulative balance of 14 - Not redeemed any yet ( 0 ) - They then redeem a free coffee. This means that they now have: - A balance of 4 (14-10=4) - An earned balance of 0 (a balance of 4 is not enough to earn a free coffee.) - A lifetime cumulative balance of 14 - A redeemed balance of 1

Success XML Response for a Coalition campaign:

  <response status="success">
    <customer>
      <code>89898989898989</code>
      <card_number>1212121212</card_number>
      <first_name>John</first_name>
      <last_name>Doe</last_name>
      <phone>555-5555</phone>
      <email>john@email.com</email>
      <street1>123 Main St.</street1>
      <street2>Apt 3G</street2>
      <city>Anytown</city>
      <state>ONT</state>
      <postal_code>55555</postal_code>
      <country>New Zealand</country>
      <custom_date>1970-07-14</custom_date>
      <custom_field>He Likes Cheese</custom_field>
      <customer_username>jdoe1970</customer_username>
      <registered>Y</registered>
      <custom_field_2>
        <label>Marital Status</label>
        <data>Single</data>
      </custom_field_2>
      ...
    </customer>
    <campaigns>
      <campaign>
        <id>1234567890123456</id>
        <name>Widget Rewards</name>
        <type>points</type>
        <balance>1500</balance>
        <cumulative>0</cumulative>
        <last_transaction>2011-12-31</last_transaction>
        <balance_coalition>1500</balance_coalition>
        <cumulative_coalition>8350</cumulative_coalition>
        <available_rewards>
          <reward>
            <id>678</id>
            <description>Free Widget</description>
            <needed_to_redeem>1000</needed_to_redeem>
            <reward_id>A-345678</reward_id>
          </reward>
          <reward>
            <id>753</id>
            <description>Free bigger widget</description>
            <needed_to_redeem>2500</needed_to_redeem>
          </reward>
        </available_rewards>
      </campaign>
      <campaign>
        <id>0123456123456789</id>
        <name>ACME Rewards</name>
        <type>points</type>
        <balance>1500</balance>
        <cumulative>4500</cumulative>
        <last_transaction>2011-12-31</last_transaction>
        <balance_coalition>1500</balance_coalition>
        <cumulative_coalition>8350</cumulative_coalition>
        <available_rewards>
          <reward>
            <id>678</id>
            <description>Free Widget</description>
            <needed_to_redeem>1000</needed_to_redeem>
            <reward_id>A-345678</reward_id>
          </reward>
          <reward>
            <id>753</id>
            <description>Free bigger widget</description>
            <needed_to_redeem>2500</needed_to_redeem>
          </reward>
        </available_rewards>
      </campaign>
    </campaigns>
  </response>

Notes

XML Response if no customer matches code or card_number given:

  <response status="no_match">
    <message>Language-specific "No Customers Match Criteria"</message>
  </response>

Error XML Response:

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

Customer - Balance & History

Returns a customer's balance and transaction history for a particular campaign. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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

$data['type'] = 'customer_balance';
$data['account_id'] = 'greatwidgets';
$data['campaign_id'] = 'Store Rewards';
$data['code'] = '1234567890123456';
or
$data['card_number'] = '29374856';

Request Parameters

Name Example/Description Required
type customer_balance Yes
account_id Name of tenant Yes
campaign_id 1111222233334444 See Notes
code or card_number 1234567890123456 or 234566 Yes
transactions_number 0 for none 1 to 9999... Optional
across_campaigns Yes Optional
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

General Notes - When using this call with 'code', it must be the unique Customer ID that was either passed as 'code' by your program when the customer record was created previously, or the 16-digit number that was generated by us and returned to you in the API response. - The transactions_number field lets you specify how many transactions to return along with the balance: - A value of 0 means none will be returned. - Anything above 0 will return the number of transactions specified. - Not providing this field returns ALL transactions. - For coalition accounts, the balance will be the coalition balance, not the individual campaign balance. Hence the totals of the transactions may not add up to the coalition balance, since the customer may have other transactions in other campaign(s). Only the transactions for this campaign will be listed. - To have the customer history of the customer's transactions in a coalition account (only) include all the transactions in all the campaigns that resulted in the balance, include the parameter across_campaigns set to Yes.

Success XML Response (Points-Based Campaign):

  <response status="success">
    <campaign>
      <campaign_id>4857302875023023</campaign_id>
      <campaign_type>points</campaign_type>
      <campaign_name>Store_Rewards</campaign_name>
      <customer>
        <code>1234567890123456</code>
        <balance>1500</balance>
        <last_transaction>2011-12-15</last_transaction>
        <last_redemption>2011-12-31</last_redemption>
        <transactions>
          <transaction>
            <id>4056</id>
            <date>2011-12-15</date>
            <amount>20000</amount>
            <orig_amount>200</orig_amount>
            <redeemed>N</redeemed>
            <authorization>Purchased Item</authorization>
            <user_name>employee1</user_name>
          </transaction>
          <transaction>
            <id>4097</id>
            <date>2011-21-31</date>
            <amount>-15000</amount>
            <redeemed>Y</redeemed>
            <authorization>Redeemed Item</authorization>
            <user_name>employee2</user_name>
          </transaction>
          ...
        </transactions>
      </customer>
    </campaign>
</response>

Success XML Response (Points-Based Campaign with Spend-to-Reward ratio set):

  <response status="success">
    <campaign>
      <campaign_id>4857302875023023</campaign_id>
      <campaign_type>points</campaign_type>
      <campaign_name>Store_Rewards</campaign_name>
      <reward_ratio>10</reward_ratio>
      <customer>
        <code>1234567890123456</code>
        <balance>1500</balance>
        <equivalent_cash_balance>1.50</equivalent_cash_balance>
        <equivalent_cash_currency>Euro</equivalent_cash_currency>
        <equivalent_cash_glyph>&euro;</equivalent_cash_glyph>
        <last_transaction>2011-12-15</last_transaction>
        <last_redemption>2011-12-31</last_redemption>
        <transactions>
          <transaction>
            <id>4056</id>
            <date>2011-03-15</date>
            <amount>20000</amount>
            <orig_amount>200</orig_amount>
            <redeemed>N</redeemed>
            <authorization>Purchased Item</authorization>
            <user_name>employee1</user_name>
          </transaction>
          <transaction>
            <id>4097</id>
            <date>2011-12-31</date>
            <amount>-50-0</amount>
            <equivalent_cash_amount>-5.00</equivalent_cash_amount>
            <redeemed>Y</redeemed>
            <authorization>Redeemed Item</authorization>
            <user_name>employee2</user_name>
          </transaction>
          ...
        </transactions>
      </customer>
    </campaign>
</response>

Success XML Response (Points-Based Campaign with Custom Fields):

  <response status="success">
    <campaign>
      <campaign_id>4857302875023023</campaign_id>
      <campaign_type>points</campaign_type>
      <campaign_name>Store_Rewards</campaign_name>
      <customer>
        <code>1234567890123456</code>
        <balance>1500</balance>
        <equivalent_cash_balance>1.50</equivalent_cash_balance>
        <equivalent_cash_currency>Euro</equivalent_cash_currency>
        <equivalent_cash_glyph>&euro;</equivalent_cash_glyph>
        <last_transaction>2011-12-15</last_transaction>
        <last_redemption>2011-12-31</last_redemption>
        <transactions>
          <transaction>
            <id>4056</id>
            <date>2011-12-15</date>
            <amount>20000</amount>
            <orig_amount>200.00</orig_amount>
            <redeemed>N</redeemed>
            <authorization>Purchased Item</authorization>
            <user_name>employee1</user_name>
            <custom_field_2>
              <label>quantity</label>
              <data>2</data>
            </custom_field_2>
          </transaction>
          <transaction>
            <id>4097</id>
            <date>2011-12-31</date>
            <amount>-5000</amount>
            <redeemed>Y</redeemed>
            <authorization>Redeemed Item</authorization>
            <user_name>employee2</user_name>
            <custom_field_2>
              <label>quantity</label>
              <data>1</data>
            </custom_field_2>
          </transaction>
          ...
        </transactions>
      </customer>
    </campaign>
</response>

Success XML Response (Gift Card Campaign):

  <response status="success">
    <campaign>
      <campaign_id>57203576293875493</campaign_id>
      <campaign_type>giftcard</campaign_type>
      <campaign_name>Gift Basket</campaign_name>
      <customer>
        <code>1234567890123456</code>
        <balance>36.75</balance>
        <last_transaction>2011-12-15</last_transaction>
        <last_redemption>2011-12-31</last_redemption>
        <transactions>
          <transaction>
            <id>4056</id>
            <date>2011-12-15</date>
            <amount>40</amount>
            <redeemed>N</redeemed>
            <authorization>Cash Added</authorization>
            <user_name>employee2</user_name>
          </transaction>
          <transaction>
            <id>4097</id>
            <date>2011-12-31</date>
            <amount>-3.25</amount>
            <redeemed>Y</redeemed>
            <authorization>Cash Redeemed</authorization>
            <user_name>employee2</user_name>
          </transaction>
          ...
        </transactions>
      </customer>
    </campaign>
</response>

Success XML Response (Buy-X-Get_One-Free / Membership Campaign):

   <response status="success">
     <campaign>
       <campaign_id>53485702387562034</campaign_id>
       <campaign_type>buyx</campaign_type>
       <campaign_name>Club Fantastic</campaign_name>
       <customer>
         <code>1234567890123456</code>
         <balances>
           <item>
             <name>Coffees</name>
             <balance>14</balance>
             <earned>1</earned>
           </item>
           <item>
             <name>Cakes</name>
             <balance>7</balance>
             <earned>0</earned>
           </item>
           <item>
             <name>Books</name>
             <balance>2</balance>
             <earned>0</earned>
           </item>
         </balances>
         <last_transaction>2011-12-15</last_transaction>
         <last_redemption>2011-12-31</last_redemption>
         <transactions>
           <transaction>
             <id>4056</id>
             <date>2011-12-15</date>
             <service_product>Coffees</service_product>
             <amount>12</amount>
             <redeemed>N</redeemed>
             <authorization>Purchased Items</authorization>
             <user_name>employee1</user_name>
           </transaction>
           <transaction>
             <id>4097</id>
             <date>2011-12-31</date>
             <service_product>Cakes</service_product>
             <amount>1</amount>
             <redeemed>Y</redeemed>
             <authorization>Redeemed Items</authorization>
             <user_name>employee1</user_name>
           </transaction>
           ...
         </transactions>
       </customer>
     </campaign>
</response>
    ```
**Notes**

- The **<balance>** is the amount of purchases that have accumulated
- The **<earned>** is the amount of items that the customer has earned based on the **<balance>** of items purchased.
- The **<balance>** is not a cumulative balance -- It is the current balance of purchases that count towards the calculation of **<earned>** items.
- When an **<earned>** item is redeemed, the amount of items that were needed to earn it are deducted from the **<balance>**
- For example: A customer purchases **14** coffees. They earn **1** free coffee per **10** purchased (this ratio is defined when a campaign is created or updated and is also reported in the Campaign - List BuyX Items API call). This this means that with a **<balance>** of **14** they have **<earned> 1** free Coffee. They then redeem it (get a free one) and their **<balance>** is now **4** (14-10=4) and with only 4 they have now **<earned> 0** (have not yet earned any.)

> Success XML Response (Events (Visits) Based Campaign):

```php
  <response status="success">
    <campaign>
      <campaign_id>683979284679238</campaign_id>
      <campaign_type>events</campaign_type>
      <campaign_name>Frequent Shopper</campaign_name>
      <customer>
        <code>1234567890123456</code>
        <balance>23</balance>
        <last_transaction>2011-12-15</last_transaction>
        <last_redemption>2011-12-31</last_redemption>
        <transactions>
          <transaction>
            <id>4056</id>
            <date>2011-12-15</date>
            <amount>1</amount>
            <redeemed>N</redeemed>
            <authorization>Visit Note</authorization>
            <user_name>employee1</user_name>
            <transaction>
            </transaction>
            <id>4097</id>
            <date>2011-12-31</date>
            <amount>-10</amount>
            <redeemed>Y</redeemed>
            <authorization>Redeemed Reward</authorization>
            <user_name>employee2</user_name>
          </transaction>
          ...
        </transactions>
      </customer>
    </campaign>
</response>

Success XML Response (Earn-per-Event Based Campaign):

 <response status="success">
   <campaign>
     <campaign_id>325702938572039</campaign_id>
     <campaign_type>earned</campaign_type>
     <campaign_name>Referral Rewards</campaign_name>
     <customer>
       <code>1234567890123456</code>
       <balance>105.00</balance>
       <last_transaction>2011-12-15</last_transaction>
       <last_redemption>2011-12-31</last_redemption>
       <transactions>
         <transaction>
           <id>4056</id>
           <date>2011-12-15</date>
           <amount>4.50</amount>
           <redeemed>N</redeemed>
           <authorization>Event Earning</authorization>
           <user_name>employee1</user_name>
         </transaction>
         <transaction>
           <id>4097</id>
           <date>2011-12-31</date>
           <amount>-29.95</amount>
           <redeemed>Y</redeemed>
           <authorization>Redeemed reward</authorization>
           <user_name>employee1</user_name>
         </transaction>
         ...
       </transactions>
     </customer>
   </campaign>
</response>

Error XML Response:

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

Customer - Delete

Deletes a customer from an account PERMANENTLY.

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

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Request Parameters

Name Example/Description Required
type customer_delete Yes
account_id Name of tenant Yes
code 1234567890123456 or 234566 Yes
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

WARNING: THIS IS A PERMANENT DELETE. THERE IS NO UNDO! This call deletes ALL information related to that customer: - Removes ALL customer data such as name, card number, etc. - Removes ALL customer transactions in ALL account campaigns. - Removes ONLY one customer at a time to avoid accidentally wiping the whole database.

General Notes - If you want to remove more than one customer at a time, implement a loop in your code that makes this call for each customer that you want removed. This way, if the whole customer database gets erased accidentally, the fault lies with your code, not ours.

Example PHP Requests

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

$data['type'] = 'customer_delete';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';

Success XML Response

  <response status="success">
    <customer status="deleted">
      <code>1234567890123456</code>
    </customer>
  </response>

Error XML Response

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

Customer - Validate

Determines if a customer's password is valid. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests If you are using PHP request, the $data array would look like:

$data['type'] = 'validate_customer_password';
$data['account_id'] = 'greatwidgets';
$data['card_number'] = '121212121212';
$data['customer_password'] = 'pa$$w0rd';

Request Parameters

Parameter Name Example/Description Required
type validate_customer_password Yes
account_id Name of tenant Yes
card_number 1212121212 See Notes
code 1234567890123456 See Notes
customer_username jdoe1970 See Notes
customer_password pa$$w0rd See Notes
customer_PIN 1234 See Notes
phone 5551115555
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

General Notes - Either the card_number, customer code, or customer_username is REQUIRED. - Either the customer_password or customer_PIN is REQUIRED - Use any combination of parameters. Success will only be returned if ALL passed parameters are matched. (ie. you can validate on card_number + customer_password or customer_username + customer_PIN or card_number + code + customer_PIN or on all 5 parameters.) - If passing the customer code, this MUST be the unique Customer ID that was either - passed as 'code' by your program when the customer record was created previously, or - the 16-digit number that was generated by us and returned to you in the API response.

Success XML Response (password matches the one on record):

  <response status="success">
  </response>

Error XML Response (password does not match the one on record):

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

Card Replace

Updates a customer's card_number and/or unique code with new ones, based on partial customer data matching. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Request To replace the card number and/or code of a known card, by previous_code or by previous_card:

$data['type'] = 'card_replace';
$data['account_id'] = 'greatwidgets';
$data['previous_code'] = '012345678912345';
$data['new_card_number'] = '1231313';

Example PHP Request To replace the card number and/or code knowing only certain data:

$data['type'] = 'card_replace';
$data['account_id'] = 'greatwidgets';
$data['last_name'] = 'Doe';
$data['phone'] = '555-55555';
$data['customer_password'] = '1234';

Example PHP Request To replace the card number and/or code after selecting a customer from multiple matches:

$data['type'] = 'card_replace';
$data['account_id'] = 'greatwidgets';
$data['profile_uid'] = '365';
$data['new_code'] = '1234567890123456';
$data['new_card_number'] = '131313';

Request Parameters

Parameter Name Example/Description Required
type card_replace Yes
account_id Name of tenant Yes
previous_code 0123456789012345 See notes
previous_card 121212 See notes
new_code 1234567890123456 See notes
new_card_number 131313 See notes
card_number_generate (# of digits) See notes
profile_uid 395 See notes
check_override Y See notes
keep_which matched or duplicate See notes
first_name Jane Optional
last_name Doe Optional
phone 555-5555 Optional
email jdoe@email.com Optional
street1 123 Main St.
street2 Suite 3G
city Anytown Optional
state ONT Optional
postal_code 55555 Optional
country Canada
custom_date 1970-07-14 Optional
custom_field baltimore Optional
customer_password pa$$w0rd Optional
customer_PIN 1234 Optional
customer_username janedoe123 Optional
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


General Notes - For this call to work, you must provide a new_code, a new_card_number or the field card_number_generate. It can also be a combination of new_code and either new_card_number or card_number generate. - The card_number_generate field is should be included only if you want the program to generate a random unique card number. It takes as an argument the number of digits to be generated. - If both previous_code and previous_card are given, previous_code is given priority and used to identify the old card. - If neither previous_code and previous_card are given, the new_code and/or new_card_number will be applied only if there is a single resulting customer that matches ALL of whichever information fields were given (phone, email, etc.). - If multiple matches result, then a list of those matching customers will be returned, with each customer's information, including a profile_uid field to be used when one of the customers is selected as the one to update: - With a profile_uid field provided, only the new_code and/or new_card_number fields need to be given back through the API call: All other optional fields, if given, will be ignored. - The program will check before replacing any card if the given new_code or new_card_number already exist in the system -- if they do, an error code will be generated. In case this is not what you want, set the check_override parameter to Yand it will not perform this check. - Setting the check_override really only makes sense if you expect duplicate records to result from the card_replace API call. However, although card_numbers can be duplicates for esoteric reasons, card codes must be unique. If there is an existing (duplicate) card code that matches the new_code provided, for example, if joining two customer accounts together or if replacing a lost card with a new card when all cards are already pre-loaded into the system, you need to set the check_override parameter to Y AND select which of the two record to keep with the keep_which parameter: - Selecting matched will keep the customer information in the matched (or old or lost) card, replace its code and/or card number with the new one(s), delete the duplicate existing account that matches the new_code provided, and move any existing transactions associated with the now deleted duplicate account to the newly updated matched one. - Selecting duplicate will keep the customer information in the existing account whose code matches the given new_code, replace the existing card_number of that account if a new_card_number is given (or card_number_generate), delete the old (or lost) account, and move any transaction associated with the old (or lost) account to the new one. - The custom_date field must be given in YYYY-MM-DD format - Text-based matches on the optional fields are not case-sensitive.

Success XML Response for multiple matches:

  <response status="multiple_matches">
    <customers>
      <customer>
        <profile_uid>365</profile_uid>
        <code>0123456789012345</code>
        <card_number>121212</card_number>
        <first_name>John</first_name>
        <last_name>Doe</last_name>
        <phone>555-5555</phone>
        <email>jdoe@email.com</email>
        <street1>123 Main St</street1>
        <street2>Apt 3G</street2>
        <city>Anytown</city>
        <state>ONT</state>
        <postal_code>55555</postal_code>
        <country>Australia</country>
        <custom_date>1970-07-14</custom_date>
        <custom_field>Baltimore</custom_field>
      </customer>
      <customer>
        <profile_uid>1267</profile_uid>
        <code>2345678901234567</code>
        <card_number>343435</card_number>
        <first_name>John</first_name>
        <last_name>Doe</last_name>
        <phone>555-7777</phone>
        <email>john.doe@workemail.com</email>
        <street1>78 Side St</street1><street2>Apt 3G
        <street2></street2>
        <city>Bigtown</city>
        <state>CA</state>
        <postal_code>MX5-4F6</postal_code>
        <country>Oceania</country>
        <custom_date>1985-06-18</custom_date>
        <custom_field></custom_field>
      </customer>
      ...
    </campaign>
  </response>

Success XML Response if no customers matched:

  <response status="no_match">
    <message>Language-specific "No Customers Match Criteria"</message>
  </response>

Error XML Response

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

Transactions

Transaction - Record

Record a transaction for a customer account. The data submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Request Parameters

Parameter Name Example/Description Required
type record_activity Yes
account_id Name of tenant Yes
code
or
card_number		 1234567890123456
or
11112222		 Yes
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

Request Parameters for Points-Based Campaigns

Name Example/Description Required
campaign_id 1111222233334444 Yes
amount 9.95 or 9,95 Optional
promo_id 89 Do not include if none
authorization Custom description Optional
send_transaction_email Y Do not include if none to be sent.
custom_field_# Store 35 See Notes.
custom_field_# 238479237t2t3 See Notes.

Request Parameters for Gift-Card Campaigns

Name Example/Description Required
campaign_id 22223333444455555 Yes
amount 9.95 or 9,95 Yes
authorization Custom description Optional
send_transaction_email Y Do not include if none to be sent.
custom_field_# Store 35 See Notes.
custom_field_# 238479237t2t3 See Notes.

Request Parameters for Buy-X-Get-One-Free / Membership Campaigns

Name Example/Description Required
campaign_id 5555666677778888 Yes
service_product 96
or
item_identifier		 Yes
buyx_quantity 10 Optional
authorization Custom description Optional
send_transaction_email Y Do not include if none to be sent.
custom_field_# Store 35 See Notes.
custom_field_# 238479237t2t3 See Notes.

Request Parameters for Events (Visits) Based Campaigns

ParameterName Example/Description Required
campaign_id 3333444455556666 Yes
authorization Custom description Optional
send_transaction_email Y Do not include if none to be sent.
custom_field_# Store 35 See Notes.
custom_field_# 238479237t2t3 See Notes.

Request Parameters for Earn-per-Event (Visits) Campaigns

Name Example/Description Required
campaign_id 4444555566667777 Yes
authorization Custom description Optional
send_transaction_email Y Do not include if none to be sent.
custom_field_# Store 35 See Notes.
custom_field_# 238479237t2t3 See Notes.

General Notes - When using this call and using the code parameter to identify a customer, the code MUST be the unique Customer ID that was either - passed as code= by your program when the customer record was created previously, or - the 16-digit number that was generated by us when the customer account was created and returned to you in the API response. Otherwise, pass the customer's card number or membership identifier as the card_number. - If you don't know what either the code or card_number are, you can search for a customer using any of their information (like phone #, or other custom field marked as searchable by using the customer_search or customer_find API calls to retrieve the customer's code. - New customer accounts are automatically created when a transaction is received and the account/card code is not in the system already. - The field values promo_id for Points campaigns and service_product for BuyX campaigns can be found by calling the Campaign Promotions and BuyX Campaign Items List API calls. - For coalition accounts, the balance for each campaign will be the coalition balance, not the individual campaign balance. Hence the totals of the transactions for each campaign may not add up to the coalition balance, since the customer may have multiple transactions in multiple campaign(s). - To know what the custom_field_# of a custom field is, issue the Transactions Fields - List API call to get a list of the current defined custom transaction fields.

Example PHP Requests Points-Based Campaign:

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

$data['type'] = 'record_activity';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';
$data['campaign_id'] = '1111222233334444';
$data['amount'] = '9.95';
$data['promo_id'] = '89';
$data['authorization'] = 'Custom description';
$data['custom_field_2'] = 'Store 35';
$data['custom_field_5'] = 'Some other data';
$data['send_transaction_email'] = 'Y';

Success XML Response for Points Campaign

<response status="success">
  <receipt>
    <account_name>Demo Business</account_name>
    <campaign>
      <id>1111222233334444</id>
      <name>Widget Rewards</name>
    </campaign>
    <customer>
      <first_name>John</first_name>
      <last_name>Smmith</last_name>
      <card_number>11112222</card_number>
      <phone>555-5555</phone>
      <email>jsmith@workemail.com</email>
      <custom_field>He likes cheese</custom_field>
      <custom_date>1970-07-14</custom_date>
    </customer>
    <transaction>
      <id>1234</id>
      <purchase>
        <amount>9.95</amount>
        <currency>USD</currency>
      </purchase>
      <promotion>
        <description>Double Points Tuesday</description>
        <operation>x</operation>
        <amount>2</amount>
      </promotion>
      <recorded>
        <points>1990</points>
        <description>Optional note here</description>
      </recorded>
      <balance>
        <points>4590</points>
        <monetary>4.75</monetary>
        <currency>USD</currency>
      </balance>
      <cumulative_balance>
        <points>78390</points>
        <monetary>43.50</monetary>
        <currency>USD</currency>
      </cumulative_balance>
    </transaction>
  </receipt>
</response>

Notes: - The response XML will include information that can be used to print a receipt. - The operation in the promotion describes either a multiplication (x) or addition (+).

Success XML Response for Gift Card Campaign:

<response status="success">
  <receipt>
    <account_name>Demo Business</account_name>
    <campaign>
      <id>2222333344445555</id>
      <name>Gift Card</name>
    </campaign>
    <customer>
      <first_name>John</first_name>
      <last_name>Smmith</last_name>
      <card_number>11112222</card_number>
      <phone>555-5555</phone>
      <email>jsmith@workemail.com</email>
      <custom_field>He likes cheese</custom_field>
      <custom_date>1970-07-14</custom_date>
    </customer>
    <transaction>
      <id>1234</id>
      <add>
        <amount>9.95</amount>
        <currency>USD</currency>
        <description>Optional note here</description>
      </add>
      <balance>
        <amount>48.75</amount>
        <currency>USD</currency>
      </balance>
      <cumulative_balance>
        <amount>413.50</amount>
        <currency>USD</currency>
      </cumulative_balance>
    </transaction>
  </receipt>
</response>

Note:The response XML will include information that can be used to print a receipt

Success XML Response for Events Campaign:

<response status="success">
  <receipt>
    <account_name>Demo Business</account_name>
    <campaign>
      <id>3333444455556666</id>
      <name>Frequent Shopper</name>
    </campaign>
    <customer>
      <first_name>John</first_name>
      <last_name>Smmith</last_name>
      <card_number>11112222</card_number>
      <phone>555-5555</phone>
      <email>jsmith@workemail.com</email>
      <custom_field>He likes cheese</custom_field>
      <custom_date>1970-07-14</custom_date>
    </customer>
    <transaction>
      <id>1234</id>
      <event>
        <description>Optional note here</description>
        <amount>9.95</amount>
      </event>
      <balance>
        <events>12</events>
      </balance>
      <cumulative_balance>
        <events>25</events>
      </cumulative_balance>
    </transaction>
  </receipt>
</response>

Success XML Response for Earn-per-Event Campaign

<response status="success">
  <receipt>
    <account_name>Demo Business</account_name>
    <campaign>
      <id>4444555566667777</id>
      <name>GateKeeper Rewards</name>
    </campaign>
    <customer>
      <first_name>John</first_name>
      <last_name>Smmith</last_name>
      <card_number>11112222</card_number>
      <phone>555-5555</phone>
      <email>jsmith@workemail.com</email>
      <custom_field>He likes cheese</custom_field>
      <custom_date>1970-07-14</custom_date>
    </customer>
    <transaction>
      <id>1234</id>
      <event>
        <description>Optional note here</description>
      </event>
      <earn>
        <amount>4.50</amount>
        <currency>USD</currency>
      </earn>
      <balance>
        <amount>22.50</amount>
        <currency>USD</currency>
      </balance>
      <cumulative_balance>
        <amount>45.00</amount>
        <currency>USD</currency>
      </cumulative_balance>
    </transaction>
  </receipt>
</response>

Success XML Response for Buy-X-Get-One-Free Campaign

<response status="success">
  <receipt>
    <account_name>Demo Business</account_name>
    <campaign>
      <id>5555666677778888</id>
      <name>Widget Rewards</name>
    </campaign>
    <customer>
      <first_name>John</first_name>
      <last_name>Smmith</last_name>
      <card_number>11112222</card_number>
      <phone>555-5555</phone>
      <email>jsmith@workemail.com</email>
      <custom_field>He likes cheese</custom_field>
      <custom_date>1970-07-14</custom_date>
    </customer>
    <transaction>
      <id>1234</id>
      <purchase>
        <item>Books</item>
        <quantity>2</quantity>
      <description>Optional note here</description>
      </purchase>
      <balances>
        <item>
          <name>Books</name>
          <current>14</current>
          <cumulative>14</cumulative>
        </item>
        <item>
          <name>Coffees & Teas</name>
          <current>6</current>
          <cumulative>43</cumulative>
        </item>
        <item>
          <name>Cakes & Cookies</name>
          <current>2</current>
          <cumulative>12</cumulative>
        </item>
        ...
      </balances>
    </transaction>
  </receipt>
</response>

Error XML Response

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

Transaction - Redeem

Record a redemption transaction for a customer account. The data to be submitted to the API is composed of the following fields:

Fields common to all campaign types

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Request Parameters

Parameter Name Example/Description Required
type redeem Yes
account_id Name of tenant Yes
code 1234567890123456 Yes
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

Request Parameters for Points-Based Campaigns

Parameter Name Example/Description Required
campaign_id 1111222233334444 Yes
custom_points_redeem
or
custom_dollars_redeem
or
reward_to_redeem		 100
or
9.95 or 9,95
or
98		 Yes, At least one of these three
authorization Custom description Optional

Note: Use the campaign_rewards API call to list the available rewards and their IDs

Request Parameters for Gift-Card Campaigns:

Parameter Name Example/Description Required
campaign_id Gift Basket Yes
reward_to_redeem 9.95 or 9,95 Yes
authorization Custom description Optional

Request Parameters for Buy-X-Get-One-Free / Membership Campaigns:

Parameter Name Example/Description Required
campaign_id Club Fantastic Yes
reward_to_redeem 96 (the item_id)
or
[item_identifier]		 Yes, See note below
authorization Custom description Optional

**Note: Use the buyx_items_list API call to list available items and their IDs.*

Request Parameters for Events (Visits) Based Campaigns:

Parameter Name Example/Description Required
campaign_id Frequent Shopper Yes
reward_to_redeem 41 Yes, See note below
authorization Custom description Optional


Note: Use the campaign_rewards API call to list the available rewards and their IDs

Request Parameters for Earn-per-Event (Visits) Campaigns:

Parameter Name Example/Description Required
campaign_id Referral Rewards Yes
reward_to_redeem 9.95 or 9,95 Yes
authorization Custom description Optional

General Notes - 'When using this call, the code MUST be the unique Customer ID that was either: - passed as code by your program when the customer record was created previously, or - the 16-digit number that was generated by us and returned to you in the API response. - Before making this call, you should check whether the customer balance is greater than the amount to be redeemed. - The reward_to_redeem field value is the id parameter that is returned in the response of the Campaign Rewards call -- OR the optional reward_id that is defined in the Campaign - New BuyX Item and Campaign - Edit BuyX Item API calls. - For coalition accounts, the balance for each campaign will be the coalition balance, not the individual campaign balance. Hence the totals of the transactions for each campaign may not add up to the coalition balance, since the customer may have multiple transactions in multiple campaign(s).

Example PHP Requests:

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

Points-Based Campaign - Pre-defined Reward:**

$data['type'] = 'redeem';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';
$data['campaign_id'] = '546734563456';
$data['reward_to_redeem'] = '98';
$data['authorization'] = 'Custom description';

Points-Based Campaign - Custom Points:

$data['type'] = 'redeem';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';
$data['campaign_id'] = '546734563456';
$data['custom_points_redeem'] = '100';
$data['authorization'] = 'Custom description';

Points-Based Campaign - Monetary Amount: Note: This capability is available ONLY if you have set a Spend-to-Reward Ratio in the point campaign's preferences.*

$data['type'] = 'redeem';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';
$data['campaign_id'] = '546734563456';
$data['custom_dollars_redeem'] = '9.95';
$data['authorization'] = 'Custom description';

Points-Based Campaign - Combination of reward types:** Note: Only one of each type can be used per call, abs the custom_dollars_redeem capability is available ONLY if you have set a Spend-to-Reward Ratio in the point campaign's preferences.*

$data['type'] = 'redeem';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';
$data['campaign_id'] = '546734563456';
$data['reward_to_redeem'] = '98';
$data['custom_points_redeem'] = '100';
$data['custom_dollars_redeem'] = '9.95';
$data['authorization'] = 'Custom description';

Gift Card Campaign

$data['type'] = 'redeem';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';
$data['campaign_id'] = '83635463645756';
$data['reward_to_redeem'] = '9.95';
$data['authorization'] = 'Custom description';

Buy-X-Get-One-Free Campaign

$data['type'] = 'redeem';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';
$data['campaign_id'] = '763446467657';
$data['reward_to_redeem'] = '96';
$data['authorization'] = 'Custom description';

Events-Based Campaign

$data['type'] = 'redeem';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';
$data['campaign_id'] = '763446467657';
$data['reward_to_redeem'] = '41';
$data['authorization'] = 'Custom description';

Earn-per-Event Campaign

$data['type'] = 'redeem';
$data['account_id'] = 'greatwidgets';
$data['code'] = '1234567890123456';
$data['campaign_id'] = '2355464634565';
$data['reward_to_redeem'] = '9.95';
$data['authorization'] = 'Custom description';

Success XML Responses Note: The response XML will include information that can be used to print a receipt. For Points Campaign

<response status="success">
  <receipt>
    <account_name>Demo Business</account_name>
    <agency>
      <id>acmemktg</id>
      <name>ACME Marketing</name>
      <email>server@acmemarkting.com</email>
    </agency>
    <campaign>
      <id>463789753832</id>
      <name>Widget Rewards</name>
    </campaign>
    <customer>
      <first_name>Jane</first_name>
      <last_name>Doe</last_name>
      <card_number>11112222</card_number>
      <phone>555-5555</phone>
      <email>jdoe@workemail.com</email>
      <custom_field>She likes cheese</custom_field>
      <custom_date>1970-07-14</custom_date>
    </customer>
    <transaction>
      <id>1234</id>
      <description>Optional note here</description>
      <reward>
        <id>98</id>
        <points>100</points>
        <description>Free Widget!</description>
      </reward>
      <custom>
        <points>150</points>
      </custom>
      <monetary>
        <amount>9.90</points>
        <currency>USD</currency>
        <points>1990</points>
      </monetary>
      <balance>
        <points>4590</points>
        <monetary>4.75</monetary>
        <currency>USD</currency>
      </balance>
      <cumulative_balance>
        <points>78390</points>
        <monetary>43.50</monetary>
        <currency>USD</currency>
      </cumulative_balance>
    </transaction>
  </receipt>
</response>

For Gift Card Campaign

  <response status="success">
    <receipt>
      <account_name>Demo Business</account_name>
      <agency>
        <id>acmemktg</id>
        <name>ACME Marketing</name>
        <email>server@acmemarkting.com</email>
      </agency>
      <campaign>
        <id>7456756743563456</id>
        <name>Gift Card</name>
      </campaign>
      <customer>
        <first_name>Jane</first_name>
        <last_name>Doe</last_name>
        <card_number>11112222</card_number>
        <phone>555-5555</phone>
        <email>jdoe@workemail.com</email>
        <custom_field>She likes cheese</custom_field>
        <custom_date>1970-07-14</custom_date>
      </customer>
      <transaction>
        <id>1234</id>
        <deduct>
          <amount>14.95</amount>
          <currency>USD</currency>
          <description>Optional note here</description>
        </deduct>
        <balance>
          <amount>40.75</amount>
          <currency>USD</currency>
        </balance>
        <cumulative_balance>
          <amount>413.50</amount>
          <currency>USD</currency>
        </cumulative_balance>
      </transaction>
    </receipt>
</response>

For Events Campaign

<response status="success">
  <receipt>
    <account_name>Demo Business</account_name>
    <agency>
      <id>acmemktg</id>
      <name>ACME Marketing</name>
      <email>server@acmemarkting.com</email>
    </agency>
    <campaign>
      <id>6576327476742</id>
      <name>Frequent Shopper</name>
    </campaign>
    <customer>
      <first_name>Jane</first_name>
      <last_name>Doe</last_name>
      <card_number>11112222</card_number>
      <phone>555-5555</phone>
      <email>jdoe@workemail.com</email>
      <custom_field>She likes cheese</custom_field>
      <custom_date>1970-07-14</custom_date>
    </customer>
    <transaction>
      <id>1234</id>
      <description>Optional note here</description>
      <reward>
        <id>41</id>
        <amount>9</amount>
        <description>Free Widget!</description>
      </reward>
      <balance>
        <events>12</events>
      </balance>
      <cumulative_balance>
        <events>25</events>
      </cumulative_balance>
    </transaction>
  </receipt>
</response>

For Earn-per-Event Campaign

<response status="success">
  <receipt>
    <account_name>Demo Business</account_name>
    <agency>
      <id>acmemktg</id>
      <name>ACME Marketing</name>
      <email>server@acmemarkting.com</email>
    </agency>
    <campaign>
      <id>8875483453453</id>
      <name>GateKeeper Rewards</name>
    </campaign>
    <customer>
      <first_name>Jane</first_name>
      <last_name>Doe</last_name>
      <card_number>11112222</card_number>
      <phone>555-5555</phone>
      <email>jdoe@workemail.com</email>
      <custom_field>She likes cheese</custom_field>
      <custom_date>1970-07-14</custom_date>
    </customer>
    <transaction>
      <id>1234</id>
      <deduct>
        <amount>14.95</amount>
        <currency>USD</currency>
        <description>Optional note here</description>
      </deduct>
      <balance>
        <amount>22.50</amount>
        <currency>USD</currency>
      </balance>
      <cumulative_balance>
        <amount>45.00</amount>
        <currency>USD</currency>
      </cumulative_balance>
    </transaction>
  </receipt>
</response>

For Buy-X-Get-One-Free Campaign

<response status="success">
  <receipt>
    <account_name>Demo Business</account_name>
    <agency>
      <id>acmemktg</id>
      <name>ACME Marketing</name>
      <email>server@acmemarkting.com</email>
    </agency>
    <campaign>
      <id>67434675463456</id>
      <name>Frequent Buyer Rewards</name>
    </campaign>
    <customer>
      <first_name>Jane</first_name>
      <last_name>Doe</last_name>
      <card_number>11112222</card_number>
      <phone>555-5555</phone>
      <email>jdoe@workemail.com</email>
      <custom_field>She likes cheese</custom_field>
      <custom_date>1970-07-14</custom_date>
    </customer>
    <transaction>
      <id>1234</id>
      <description>Optional note here</description>
      <reward>
        <service_product>Books</service_product>
        <deduct>10</deduct>
      </reward>
      <balances>
        <item>
          <name>Books</name>
          <current>14</current>
          <cumulative>14</cumulative>
        </item>
        <item>
          <name>Coffees & Teas</name>
          <current>6</current>
          <cumulative>43</cumulative>
        </item>
        <item>
          <name>Cakes & Cookies</name>
          <current>2</current>
          <cumulative>12</cumulative>
        </item>
        ...
      </balances>
    </transaction>
  </receipt>
</response>

Error XML Response

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

Transaction - Batch

Record a batch of transactions for a customer account, including redemptions. The data to be submitted to the API is composed of the following fields:

Fields common to all campaign types:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Request Parameters

Name Example/Description Required
API 1.5
account_id Name of tenant Yes
type batch_transactions Yes
delimiter pipe
or
comma
or
tab		 Yes
apply_ratio yes or no Optional, See Notes
allow-undo yes Optional: 'yes' or don't include.
send_transaction_email Y Optional: 'Y' or don't include.
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

General Notes - If apply_ratio is not given or is set to no: - Points Campaigns: - Add transaction: amount = points - Redemptions: amount = points - Giftcard Campaigns: - Add transaction: amount = monetary value. - Redemptions: amount = monetary value. - Events Campaigns: - Add transaction: amount = number of events. - Redemptions: amount = number of events. - Earned Campaigns: - Add transaction: amount = monetary value. - Redemptions: amount = monetary value. - BuyX Campaings: - Add transaction: amount = number of items purchased - Redemptions: amount = accumulated items to deduct, NOT: number of items redeemed.

Request Parameters for Points-Based Campaigns:

Parameter Name Example/Description Required
visits_header_1 campaign_id Yes
visits_header_2 code Yes
visits_header_3 redeemed Y / N
visits_header_4 amount Yes : if not used set value to none
visits_header_5 date Yes : if not used set value to none
visits_header_6 authorization Yes : if not used set value to none
visits_header_7 promo_id Optional. Single ID or separated by commas
Visits_Data see example in notes below

Notesfor Points-Based Campaigns: - code is either: - the unique Customer ID recorded in the code field when the customer account was first created AND there was no card_number, or the card_number of the customer. - If date is not given, today's date will be used. - If promo_id is used and multiple given and separated by commas, DO NOT USE the comma as delimiter. - Example Visits_Data: - Data to be imported in batch: single (text) field with **eols* at the end of each line*
1111222233334444|12121|N|14,95|2013-0315|API test import 1|123
1111222233334444|12121|N|50|2010-03-15|API test import 2|345,345,354
1111222233334444|12121|N|34.67|2010-03-15|API test import 3
1111222233334444|12121|N|0,50|2010-03-15|API test import 4
1111222233334444|12121|N|.75|2010-03-15|API test import 5
1111222233334444|12121|N|2.00|2010-03-15|API test import 6
1111222233334444|12121|Y|1500|2010-03-15|API test redeem 1

Request Parameters for Gift-Card Campaigns:

Parameter Name Example/Description Required
visits_header_1 campaign_id Yes
visits_header_2 code Yes
visits_header_3 redeemed Y / N
visits_header_4 amount Yes : if not used set value to none
visits_header_5 date Yes : if not used set value to none
visits_header_6 authorization Yes : if not used set value to none
Visits_Data see example in notes below

Notes - code is either - the unique Customer ID recored in the code field when the customer account was first created AND there was no card_number, or the card_number of the customer. - If date is not given, today's date will be used. - Example Visits_Data : - Data to be imported in batch: single (text) field with **eols* at the end of each line*
1111222233334444|12121|N|14,95|2010-03-15|API test import 1
1111222233334444|12121|N|34.67|2010-03-15|API test import 2
1111222233334444|12121|Y|49.62|2010-03-15|API test redeem 1

Request Parameters for Buy-X-Get-One-Free / Membership Campaigns:

Parameter Name Example/Description Required
visits_header_1 campaign_id Yes
visits_header_2 code Yes
visits_header_3 redeemed Y / N
visits_header_4 service_product Yes
visits_header_5 amount Yes : if not used set value to none
visits_header_6 date Yes : if not used set value to none
visits_header_7 authorization Yes : if not used set value to none
Visits_Data see example in notes below

Notes - code is either: - the unique Customer ID recored in the code field when the customer account was first created AND there was no card_number, or - the card_number of the customer. - If date is not given, today's date will be used. - service_product is not the id but the description of the Item returned by the BuyX Campaign Items List API call. This is because some clients import lists of transaction with items they did not pre-enter in the admin interface. Thus, the import does allows new (service_product) items to be used that have not been pre-defined. - The caveat is that each service_product name must be exactly spelled and capitalized the same, usually not an issue when that information is taken from another database or output from a POS or inventory management system. - Example of Visits_Data : - Data to be imported in batch: single (text) field with **eols* at the end of each line*
1111222233334444|12121|N|Coffees|3|2010-03-15|API test import 1
1111222233334444|12121|N|Cakes|1|2010-03-15|API test import 2
1111222233334444|12121|Y|Coffees|1|2010-03-15|API test redeem 1

Request Parameters for Events (Visits) Based Campaigns:

Parameter Name Example/Description Required
visits_header_1 campaign_id Yes
visits_header_2 code Yes
visits_header_3 redeemed Y / N
visits_header_4 date Yes: if not used set value to none
visits_header_5 authorization Yes : if not used set value to none
visits_header_6 amount If redeemed = Y then Required else set array key to none
Visits_Data see example in notes below

Notes - code is either: - The unique Customer ID recored in the code field when the customer account was first created AND there was no card_number), or - The card_number of the customer. - If date is not given, today's date will be used. - Examples of Visits_Data : - Data to be imported in batch: single (text) field with **eols* at the end of each line*
1111222233334444|12121|N|2010-03-15|API add event
1111222233334444|12121|N|2010-03-15|API add event
- Redemptions to be imported in batch: Single (text) field with **eols* at end of each line:*
1111222233334444|12121|Y|2010-03-15|API redeem|2.

Request Parameters for Earn-per-Event (visits) Campaigns:

Parameter Name Example/Description Required
visits_header_1 campaign_id Yes
visits_header_2 code Yes
visits_header_3 redeemed Y / N
visits_header_4 date Yes : if not used set value to none
visits_header_5 authorization Yes : if not used set value to none
visits_header_6 amount If redeemed = Y then Required else set array key to none
Visits_Data See Examples in Notes below

Example PHP Requests for Points-Based Campaign Pre-defined Reward:

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

$data['API'] = '1.5';
$data['account_id'] = 'greatwidgets';
$data['type'] = 'batch_transactions';
$data['delimiter'] = 'pipe';
$data['apply_ratio'] = 'yes';
$data['allow-undo'] = 'yes';
$data['visits_header_1'] = 'campaign_id';
$data['visits_header_2'] = 'code';
$data['visits_header_3'] = 'redeemed';
$data['visits_header_4'] = 'amount';
$data['visits_header_5'] = 'date';
$data['visits_header_6'] = 'custom_field_3';
$data['Visits_Data'] = '
4638472975924871|12121|N|14,95|2010-03-15|API test import 1
4638472975924871|12121|N|50|2010-03-15|API test import 2
4638472975924871|12121|N|34.67|2010-03-15|API test import 3
4638472975924871|12121|N|0,50|2010-03-15|API test import 4
4638472975924871|12121|N|.75|2010-03-15|API test import 5
4638472975924871|12121|N|2.00|2010-03-15|API test import 6
4638472975924871|12121|Y|1500|2010-03-15|API test redeem 1
';

Success XML Responses

<response status="success">
  <batch status="all_imported">
    <transactions>7</transactions>
  </batch>
</response>

Error XML Response:

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

Transaction - Delete

Deletes a specific transaction in a customer account. The data to be submitted to the API is composed of the following fields:

Fields common to all campaign types:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests:

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

$data['type'] = 'transaction_delete';
$data['account_id'] = 'greatwidgets';
$data['campaign_id'] = '4564222953051300';
$data['code'] = '1234567890123456';
$data['transaction_id'] = '4056';

Request Parameters

Parameter Name Example/Description Required
type transaction_delete Yes
account_id Name of tenant Yes
campaign_id 4564222953051300 Yes
code 1234567890123456 Yes
transaction_id 4056 Yes
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

General Notes

Success XML Response for Points Campaign:

<response status="success">
</response>

Error XML Response

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

Miscellaneous calls

Token - Get

Generates a unique, self-expiring time token that can be used to authenticate a series of API calls performed by a user within a given time frame. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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

$data['API'] = '1.5';
$data['account_id'] = 'greatwidgets';
$data['type'] = 'generate_time_token';
$data['token_interval'] = '86400';

Request Parameters

Parameter Name Example/Description Required
API 1.5
account_id Name of tenant Yes
type generate_time_token Yes
token_interval 60 Optional
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

General Notes - The token_interval is optional and defines the validity of the token in seconds. If it sis not provided, it will default to 60 seconds. This means the token will no longer be valid after the time interval. If invalid, this will return an error when the Token - Validate API call is made.

Success XML Response

<response status="success">
  <token>CHFBTABPGWGBRLCKETCKGDDKEAFFBBFBETTI</token>
</response>

Error XML Response

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

Token - Validate

Validates a unique, self-expiring time token that can be used to authenticate that a series of API calls is performed by a user within a given time-frame: The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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

$data['API'] = '1.5';
$data['account_id'] = 'greatwidgets';
$data['type'] = 'validate_time_token';
$data['token'] = 'CHFBTABPGWGBRLCKETCKG';

Request Parameters

Parameter Name Example/Description Required
API 1.5
account_id Name of tenant Yes
type validate_time_token Yes
token CHFBTABPGWGBRLCKETCKG Yes
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

General Notes - The token is only given as a result of making the Token - Get API call.

Success XML Response for Points Campaign

<response status="valid">
</response>

Error XML Response

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

Audit Reports

All Transactions

Generate a report with all the transactions between two date ranges in the selected campaigns. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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

$data['account_id'] = 'greatwidgets';
$data['type'] = 'reports';
$data['report'] = 'transactions_all';
$data['date_start'] = '2010-01-01';
$data['date_end'] = '2011-12-31';
$data['selected_campaigns'] = '123456789012,210987654321';

Request Parameters

Parameter Name Example/Description Required
account_id Name of tenant Yes
type reports Yes
report transactions_all Yes
date_start 2010-01-01 Yes
selected_campaigns 123456789012,21987654321 Yes
date_end 2011-12-31 Optional
restrict_by_user cashier324 Optional
show_activations Yes Optional
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

General Notes - The date_start and date_end must be provided in ISO 8601 format: YYYY-MM-DD, where YYYY is the year in four-digit format, MM is the month in 2-digit format, and DD is the day of the month in two digit format. This avoids confusion as to which part of the date is represented in which position and allows for better sorting. - Separate each selected_campaigns with a comma (no spaces!) - Use the restrict_by_user parameter to limit the transactions to only those recorded by that user. - To include non-transaction customer activated transactions, include the parameter show_activations and set it to Yes.

Success XML Response (New / Updated User):

<response status="success">
  <transaction>
    <code>1850396893739825</code><code>1850396893739825</code>
    <date>2011-08-10</date>
    <authorization>20% Discount</authorization>
    <campaign_id>123456789012</campaign_id>
    <user_name>Store_Clerk</user_name>
    <user_custom1></user_custom1>
    <first_name>Demo</first_name>
    <last_name>McDemo</last_name>
    <phone>555-5555</phone>
    <email>mcdemo@example.com</email>
    <custom1></custom1>
    <redeemed>R</redeemed>
    <code_to_show>1111111111111</code_to_show>
    <amount_number>-250</amount_number>
    <amount_type>Points</amount_type>
    <transaction_id>4338</transaction_id>
  </transaction>
  <transaction>
    ...
  </transaction>
</response>

Error XML Response:

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

All Redeemed Transactions

Generate a report with all the redeemed transactions between two date ranges in the selected campaigns. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests:

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

$data['account_id'] = 'greatwidgets';
$data['type'] = 'reports';
$data['report'] = 'transactions_redeemed';
$data['date_start'] = '2010-01-01';
$data['date_end'] = '2011-12-31';
$data['selected_campaigns'] = '123456789012,210987654321';

Request Parameters

Parameter Name Example/Description Required
account_id Name of tenant Yes
type reports Yes
report transactions_redeemed Yes
date_start 2010-01-01 Yes
selected_campaigns 123456789012,21987654321 Yes
date_end 2011-12-31 Optional
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

General Notes - The date_start and date_end must be provided in ISO 8601 format: YYYY-MM-DD, where YYYY is the year in four-digit format, MM is the month in 2-digit format, and DD is the day of the month in two digit format. This avoids all sorts of confusion as to which part of the date is represented in which position and allows for better and more natural date-based sorting. - Separate each selected_campaigns with a comma (no spaces!)

Success XML Response (New / Updated User)

<response status="success">
  <transaction>
    <code>1850396893739825</code>
    <date>2011-08-10</date>
    <authorization>20% Discount</authorization>
    <campaign_id>123456789012</campaign_id>
    <user_name>Store_Clerk</user_name>
    <user_custom1></user_custom1>
    <first_name>Demo</first_name>
    <last_name>McDemo</last_name>
    <phone>555-5555</phone>
    <email>mcdemo@example.com</email>
    <custom1></custom1>
    <redeemed>R</redeemed>
    <code_to_show>1111111111111</code_to_show>
    <amount_number>-250</amount_number>
    <amount_type>Points</amount_type>
    <transaction_id>4338</transaction>
  </transaction>
  <transaction>
    ...
  </transaction>
</response>

Error XML Response

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

Campaign Totals

Generate a report with the campaign totals between two date ranges in the selected campaigns.* The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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

$data['account_id'] = 'greatwidgets';
$data['type'] = 'reports';
$data['report'] = 'audit_totals';
$data['date_start'] = '2010-01-01';
$data['date_end'] = '2011-12-31';
$data['selected_campaigns'] = '123456789012,210987654321';

Request Parameters

Name Example/Description Required
account_id Name of tenant Yes
type reports Yes
report audit_totals
or
coalition_points
or
coalition_stored_value		 Yes
date_start 2010-01-01 Yes
selected_campaigns 123456789012,21987654321 Yes
date_end 2011-12-31 Optional
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

General Notes - The date_start and date_end must be provided in ISO 8601 format: YYYY-MM-DD, where YYYY is the year in four-digit format, MM is the month in 2-digit format, and DD is the day of the month in two digit format. This avoids all sorts of confusion as to which part of the date is represented in which position and allows for better and more natural date-based sorting. - Separate each selected_campaigns with a comma (no spaces!) - The coalition_points and coalition_stored_value reports are used specifically for coalition or two-tier account campaigns in order to correctly report aggregated totals.

Success XML Response (New / Updated User):

<response status="success">
  <campaign>
    <campaign_name>Points Program</campaign_name>
    <campaign_type>T</campaign_type>
    <earned>4,437</earned>
    <redeemed>-3,010</redeemed>
    <liability>1,427</liability>
    <monetary_equivalent>9.51</monetary_equivalent>
    <campaign_id>123456789012</campaign_id>
  </campaign>
  <campaign>
    <campaign_name>Employee Rewards</campaign_name>
    <campaign_type>T</campaign_type>
    <earned>17,988</earned>
    <redeemed>-3,598</redeemed>
    <liability>14,390</liability>
    <monetary_equivalent>191.87</monetary_equivalent>
    <campaign_id>234567890123</campaign_id>
  </campaign>
  ...
</response>

Error XML Response

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

Customer Balances

Generate a report with all the customer balances for the given campaign. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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

$data['account_id'] = 'greatwidgets';
$data['type'] = 'reports';
$data['report'] = 'customers_balances';
$data['campaign_id'] = '123456789012';
$data['offset'] = '100';
$data['limit'] = '50';

Request Parameters

Parameter Name Example/Description Required
account_id Name of tenant Yes
type reports Yes
report customers_balances Yes
campaign_id 123456789012 Yes
offset 100 Optional
limit 50 Optional
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

General Notes - Only one selected_campaign can be run at a time. - The offset and limit are optional and can be used to generate paginated lists, or to limit the reporting range into more manageable lists.

Success XML Response (New / Updated User)

<response status="success">
  <customer>
    <card_number>12345678</card_number>
    <code>173648028775637382</code>
    <first_name>Jane</first_name>
    <last_name>Doe</last_name>
    <email>jdoe@email.com</email>
    <phone>555-5555</phone>
    <address1>123 Main St.</address1>
    <address2>Apt 3G</address2>
    <city>Anytown</city>
    <state>ND</state>
    <zip>12345</zip>
    <country>New Zealand</country>
    <custom1>She likes cheese!</custom1>
    <custom_date>1970-07-14</custom_date>
    <customer_username>jdoe123</customer_username>
    <record_timestamp>2011-05-07 14:38:59</record_timestamp>
    <earned>6021</earned>
    <redeemed>-6001</redeemed>
    <balance>20</balance>
    <balance_equivalent>0.02</balance_equivalent>
    <earned_equivalent>6.02</earned_equivalent>
    <redeemed_equivalent>-6</redeemed_equivalent>
  </customer>
  ...
</response>

Error XML Response:

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

Marketing Reports

All Customers

Generate a report with all the customers who have had transactions between two date ranges in the selected campaigns. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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

$data['account_id'] = 'greatwidgets';
$data['type'] = 'reports';
$data['report'] = 'customers_all';
$data['date_start'] = '2010-01-01';
$data['date_end'] = '2011-12-31';
$data['selected_campaigns'] = '123456789012,210987654321';

Request Parameters

Parameter Name Example/Description Required
account_id Name of tenant Yes
type reports Yes
report customers_all Yes
date_start 2010-01-01 Optional
date_end 2011-12-31 Optional
selected_campaigns 123456789012,21987654321 Optional
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

General Notes - If date_start, date_end, and selected_campaigns are not provided, customers in the database will be returned, whether they a transaction or not. - If at least one Campaign ID is provided, the customers that are returned will have a transaction in the campaign(s) - Dates provided without campaigns will be ignored. You need to provide at least one campaign in order to restrict customers who have had transactions within the date range provided. - The date_start and date_end must be provided in ISO 8601 format: YYYY-MM-DD, where YYYY is the year in a four-digit format, MM is the month in 2-digit format, and DD is the day of the month in two digit format. This format avoids confusion as to which part of the date is represented in which position and allows for better sorting. - Separate each selected_campaigns with a comma (no spaces!)

Success XML Response (New / Updated User)

<response status="success">
  <customer>
    <first_name>Jane</first_name>
    <last_name>Doe</last_name>
    <phone>555-5555</phone>
    <email>jdoe@email.com</email>
    <address1>123 Main St.</address1>
    <address2>Apt 3G</address2>
    <city>Anytown</city>
    <state>ND</state>
    <zip>12345</zip>
    <country>New Zealand</country>
    <custom1>She likes cheese!</custom1>
    <custom_date>1970-07-14</custom_date>
    <customer_username>jdoe123</customer_username>
    <customer_code>4137071924090694</customer_code>
    <card_number>11111111</card_number>
  </customer>
  <customer>
    ...
  </customer>
</response>

Error XML Response

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

New Customers

Generates a report with all the customers who have had their first transaction within the two date ranges in the selected campaigns. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests:

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

$data['account_id'] = 'greatwidgets';
$data['type'] = 'reports';
$data['report'] = 'customers_new3';
$data['date_start'] = '2010-01-01';
$data['date_end'] = '2011-12-31';
$data['selected_campaigns'] = '123456789012,210987654321';

Request Parameters

Parameter Name Example/Description Required
account_id Name of tenant Yes
type reports Yes
report customers_new Yes
date_start 2010-01-01 Yes
date_end 2011-12-31 Optional
selected_campaigns 123456789012,21987654321 Yes
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


General Notes - The date_start and date_end must be provided in ISO 8601 format: YYYY-MM-DD, where YYYY is the year in four-digit format, MM is the month in 2-digit format, and DD is the day of the month in two digit format. This avoids all sorts of confusion as to which part of the date is represented in which position and allows for better and more natural date-based sorting. Separate each selected_campaigns with a comma (no spaces!)

Success XML Response (New / Updated User):

<response status="success">
  <customer>
    <first_name>Jane</first_name>
    <last_name>Doe</last_name>
    <phone>555-5555</phone>
    <email>jdoe@email.com</email>
    <address1>123 Main St.</address1>
    <address2>Apt 3G</address2>
    <city>Anytown</city>
    <state>ND</state>
    <zip>12345</zip>
    <country>New Zealand</country>
    <custom1>She likes cheese!</custom1>
    <custom_date>1970-07-14</custom_date>
    <customer_username>jdoe123</customer_username>
    <customer_code>4137071924090694</customer_code>
    <card_number>11111111</card_number>
  </customer>
  <customer>
    ...
  </customer>
</response>

Error XML Response

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

Frequent Customers

Generate a report with all the customers who have had a certain amount of transaction between two date ranges in the selected campaigns.

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

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests: If you are using PHP request, the $data array would look like this:*

$data['account_id'] = 'greatwidgets';
$data['type'] = 'reports';
$data['report'] = 'customers_frequent';
$data['frequency'] = '10';
$data['include_redeemed'] = 'Y';
$data['date_start'] = '2010-01-01';
$data['date_end'] = '2011-12-31';
$data['selected_campaigns'] = '123456789012,210987654321';

Request Parameters

Parameter Name Example/Description Required
account_id Name of tenant Yes
type reports Yes
report customers_frequent Yes
date_start 2010-01-01 Yes
date_end 2011-12-31 Optional
selected_campaigns 123456789012,21987654321 Yes
frequency 10 Required
include_redeemed Y Optional
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

General Notes - The date_start and date_end must be provided in ISO 8601 format: YYYY-MM-DD, where YYYY is the year in four-digit format, MM is the month in 2-digit format, and DD is the day of the month in two digit format. This avoids confusion as to which part of the date is represented in which position and allows for better date-based sorting. - Separate each selected_campaigns with a comma (no spaces!) - By default include_redeemed equals No (ie: The report does not count redeem transactions.) To include those, add the include_redeemed field and set it to Y.

Success XML Response (New / Updated User)

<response status="success">
  <customer>
    <first_name>Jane</first_name>
    <last_name>Doe</last_name>
    <phone>555-5555</phone>
    <email>jdoe@email.com</email>
    <address1>123 Main St.</address1>
    <address2>Apt 3G</address2>
    <city>Anytown</city>
    <state>ND</state>
    <zip>12345</zip>
    <country>New Zealand</country>
    <custom1>She likes cheese!</custom1>
    <custom_date>1970-07-14</custom_date>
    <customer_username>jdoe123</customer_username>
    <card_number>11111111</card_number>
    <customer_code>4137071924090694</customer_code>
  </customer>

Error XML Response

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

Missing Customers

Generate a report with all the customers who have had a transaction between two date ranges in the selected campaigns, but has not been back for a given amount of days.

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

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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


$data['account_id'] = 'greatwidgets';
$data['type'] = 'reports';
$data['report'] = 'customers_missing';
$data['frequency'] = '90';
$data['include_redeemed'] = 'Y';
$data['date_start'] = '2010-01-01';
$data['date_end'] = '2011-12-31';
$data['selected_campaigns'] = '123456789012,210987654321';

Request Parameters

Parameter Name Example/Description Required
account_id Name of tenant Yes
type reports Yes
report customers_missing Yes
date_start 2010-01-01 Yes
date_end 2011-12-31 Optional
selected_campaigns 123456789012,21987654321 Yes
missing_for 90 Required (days)
include_redeemed Y Optional
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

General Notes - The date_start and date_end must be provided in ISO 8601 format: YYYY-MM-DD, where YYYY is the year in four-digit format, MM is the month in 2-digit format, and DD is the day of the month in two digit format. This avoids all sorts of confusion as to which part of the date is represented in which position and allows for better and more natural date-based sorting. - Separate each selected_campaigns with a comma (no spaces!) - By default include_redeemed equals No (ie: The report does not count redeem transactions.) To include those, add the include_redeemed field and set it to Yes.

Success XML Response (New / Updated User)

<response status="success">
  <customer>
    <first_name>Jane</first_name>
    <last_name>Doe</last_name>
    <phone>555-5555</phone>
    <email>jdoe@email.com</email>
    <address1>123 Main St.</address1>
    <address2>Apt 3G</address2>
    <city>Anytown</city>
    <state>ND</state>
    <zip>12345</zip>
    <country>New Zealand</country>
    <custom1>She likes cheese!</custom1>
    <custom_date>1970-07-14</custom_date>
    <customer_username>jdoe123</customer_username>
    <card_number>11111111</card_number>
    <customer_code>4137071924090694</customer_code>
  </customer>
  <customer>
    ...
  </customer>
</response>

Error XML Response:

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

Birthdays

Generate a report with all the customers who have had a transaction in the selected campaigns and who will celebrate a birthday in the given date range. The data to be submitted to the API is composed of the following fields:

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests:

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

$data['account_id'] = 'greatwidgets';
$data['type'] = 'reports';
$data['report'] = 'customers_birthday';
$data['date_start'] = '2010-01-01';
$data['date_end'] = '2011-12-31';
$data['selected_campaigns'] = '123456789012,210987654321';

Request Parameters

Parameter Name Example/Description Required
account_id Name of tenant Yes
type reports Yes
report customers_birthday Yes
date_start 2011-08-01 Yes
date_end 2011-08-31 Optional
selected_campaigns 123456789012,21987654321 Yes
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

General Notes - The date_start and date_end must be provided in ISO 8601 format: YYYY-MM-DD, where YYYY is the year in four-digit format, MM is the month in 2-digit format, and DD is the day of the month in two digit format. This avoids all sorts of confusion as to which part of the date is represented in which position and allows for better and more natural date-based sorting. - Separate each selected_campaigns with a comma (no spaces!)

Success XML Response (New / Updated User):

<response status="success">
  <customer>
    <first_name>Jane</first_name>
    <last_name>Doe</last_name>
    <phone>555-5555</phone>
    <email>jdoe@email.com</email>
    <address1>123 Main St.</address1>
    <address2>Apt 3G</address2>
    <city>Anytown</city>
    <state>ND</state>
    <zip>12345</zip>
    <country>New Zealand</country>
    <custom1>She likes cheese!</custom1>
    <custom_date>1970-07-14</custom_date>
    <customer_username>jdoe123</customer_username>
    <card_number>11111111</card_number>
    <customer_code>4137071924090694</customer_code>
  </customer>
  ...
</response>

Error XML Response:

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

Custom Date Range

Generate a report with all the customers who have had a transaction in the selected campaigns and whose custom_date field includes a date in the given date range.

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

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName}

Example PHP Requests

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

$data['account_id'] = 'greatwidgets';
$data['type'] = 'reports';
$data['report'] = 'customers_custom_date';
$data['date_start'] = '2010-01-01';
$data['date_end'] = '2011-12-31';
$data['selected_campaigns'] = '123456789012,210987654321';

Request Parameters

Parameter Name Example/Description Required
account_id Name of tenant Yes
type reports Yes
report customers_custom_date Yes
date_start 2011-08-01 Yes
date_end 2011-08-31 Optional
selected_campaigns 123456789012,21987654321 Yes
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

General Notes - The date_start and date_end must be provided in ISO 8601 format: YYYY-MM-DD, where YYYY is the year in four-digit format, MM is the month in 2-digit format, and DD is the day of the month in two digit format. This avoids all sorts of confusion as to which part of the date is represented in which position and allows for better and more natural date-based sorting. - Separate each selected_campaigns with a comma (no spaces!)

Success XML Response (New / Updated User):

<response status="success">
  <customer>
    <first_name>Jane</first_name>
    <last_name>Doe</last_name>
    <phone>555-5555</phone>
    <email>jdoe@email.com</email>
    <address1>123 Main St.</address1>
    <address2>Apt 3G</address2>
    <city>Anytown</city>
    <state>ND</state>
    <zip>12345</zip>
    <country>New Zealand</country>
    <custom1>She likes cheese!</custom1>
    <custom_date>1970-07-14</custom_date>
    <customer_username>jdoe123</customer_username>
    <card_number>11111111</card_number>
    <customer_code>4137071924090694</customer_code>
  </customer>
  <customer>
    ...
  </customer>
</response>

Error XML Response:

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

Generate a report with all the customers who have a transaction between two date ranges in the selected campaigns, and whose information contains the search text.

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

Header Parameters

Key Value
Content-Type application/x-www-form-urlencoded
api-key {api-key}
Authorization Bearer {access_token}
tenantName {tenantName} 
$data['account_id'] = 'greatwidgets';
$data['type'] = 'reports';
$data['report'] = 'customers_search';
$data['search_text'] = 'cheese';
$data['date_start'] = '2010-01-01';
$data['date_end'] = '2011-12-31';
$data['selected_campaigns'] = '123456789012,210987654321';

Request Parameters

Parameter Name Example/Description Required
account_id Name of tenant Yes
type reports Yes
report customers_search Yes
date_start 2010-01-01 Yes
date_end 2011-12-31 Optional
selected_campaigns 123456789012,21987654321 Yes
search_text Doe Yes
include_transactions_search Y Optional
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

General Notes - The date_start and date_end will restrict search results to only those customers that have had a transaction in that date range. - The date_start and date_end must be provided in ISO 8601 format: YYYY-MM-DD, where YYYY is the year in four-digit format, MM is the month in 2-digit format, and DD is the day of the month in two digit format. This avoids all sorts of confusion as to which part of the date is represented in which position and allows for better and more natural date-based sorting. - Separate each selected_campaigns with a comma (no spaces!) - The search_text will be searched across all customer's data, based on partial matching. - The include_transactions_search optional parameter allows searching across the customers' transactions data as well.

Example PHP Requests

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

Success XML Response (New / Updated User): php <response status="success"> <customer> <first_name>Jane</first_name> <last_name>Doe</last_name> <phone>555-5555</phone> <email>jdoe@email.com</email> <address1>123 Main St.</address1> <address2>Apt 3G</address2> <city>Anytown</city> <state>ND</state> <zip>12345</zip> <country>New Zealand</country> <custom1>She likes cheese!</custom1> <custom_date>1970-07-14</custom_date> <customer_username>jdoe123</customer_username> <card_number>11111111</card_number> <customer_code>4137071924090694</customer_code> </customer> <customer> ... </customer> </response>

Error XML Response:

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

To access the Switch APIs, see Switch.

PHP
Feedback

Keep in touch!

I'll get back to you as quickly as possible
Are you human?