Retrieve Customer Information

Retrieves a customer's information and campaigns' balances.

Headers

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

Notes:

• Headers: the user_api_key value can be included in either the header section or the body of the request. If the key is provided in both locations, the API will process and validate only the value provided in the headers.

• 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.
• In coalitions accounts only, this call will return ALL campaigns in the coalition. To ONLY show those campaigns the customer belongs to (has had a transaction with), use the show_only_belong_to parameter set to Y.

Example PHP Request:

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

1. $data['user_id'] = 'john1970';
2. $data['user_password'] = '1959caadac9b13dcb3';
3. $data['type'] = 'customer_info';
4. $data['account_id'] = 'greatwidgets';
5. $data['code'] = '89898989898989';
6. or: $data['card_number'] = 1212121212;

Success XML Response:

1. <response status="success">
2. <customer>
3. <code>89898989898989</code>
4. <card_number>1212121212</card_number>
5. <first_name>John</first_name>
6. <last_name>Doe</last_name>
7. <phone>555-5555</phone>
8. <email>john@email.com</email>
9. <street1>123 Main St.</street1>
10. <street2>Apt 3G</street2>
11. <city>Anytown</city>
12. <state>ONT</state>
13. <postal_code>55555</postal_code>
14. <country>NZ</country>
15. <custom_date>1970-07-14</custom_date>
16. <custom_field>He Likes Cheese</custom_field>
17. <customer_username>jdoe1970</customer_username>
18. <registered>Y</registered>
19. <custom_field_2>
20. <label>Marital Status</label>
21. <data>Single</data>
22. </custom_field_2>
23. ...
24. </customer>
25. <campaigns>
26. <campaign>
27. <id>1234567890123456</id>
28. <name>Widget Rewards</name>
29. <type>points</type>
30. <balance>1500</balance>
31. <cumulative>4500</cumulative>
32. <monetary_balance>10.00</monetary_balance>
33. <currency>EUR</currency>
34. <glyph>€</glyph>
35. <last_transaction>2011-12-31</last_transaction>
36. <available_rewards>
37. <reward>
38. <id>678</id>
39. <description>Free Widget</description>
40. <needed_to_redeem>1000</needed_to_redeem>
41. <reward_id>A-345678</reward_id>
42. </reward>
43. <reward>
44. <id>753</id>
45. <description>Free bigger widget</description>
46. <needed_to_redeem>2500</needed_to_redeem>
47. </reward>
48. </available_rewards>
49. </campaign>
50. <campaign>
51. <id>2345678901234567</id>
52. <name>Employee Rewards</name>
53. <type>earned</type>
54. <balance>16.50</balance>
55. <currency>EUR</currency>
56. <cumulative>59.95</cumulative>
57. <last_transaction>2011-12-31</last_transaction>
58. </campaign>
59. <campaign>
60. <id>3456789012345678</id>
61. <name>Frequent Buyer</name>
62. <type>buyx</type>
63. <balances>
64. <item>
65. <name>Coffees</name>
66. <item_id>96</item_id>
67. <balance>14</balance>
68. <earned>1</earned>
69. <cumulative>24</cumulative>
70. <redeemed>1</redeemed>
71. <earn_ratio>10</earn_ratio>
72. </item>
73. <item>
74. <name>Cakes</name>
75. <item_id>107</item_id>
76. <balance>11</balance>
77. <earned>1</earned>
78. <cumulative>21</cumulative>
79. <redeemed>1</redeemed>
80. <earn_ratio>10</earn_ratio>
81. </item>
82. <item>
83. <name>Books</name>
84. <balance>2</balance>
85. <earned>0</earned>
86. <cumulative>2</cumulative>
87. <redeemed>0</redeemed>
88. <earn_ratio>5</earn_ratio>
89. </item>
90. </balances>
91. <last_transaction>2011-12-31</last_transaction>
92. <available_rewards>
93. <reward>
94. <item_id>96</item_id>
95. <name>Coffees</name>
96. <earn_ratio>10</earn_ratio>
97. <reward_id>A-345678</reward_id>
98. </reward>
99. <reward>
100. <item_id>107</item_id>
101. <name>Cakes</name>
102. <earn_ratio>10</earn_ratio>
103. </reward>
104. </available_rewards>
105. </campaign>
106. </campaigns>
107. </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 tiems, 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 Coaltion campaign:

1. <response status="success">
2. <customer>
3. <code>89898989898989</code>
4. <card_number>1212121212</card_number>
5. <first_name>John</first_name>
6. <last_name>Doe</last_name>
7. <phone>555-5555</phone>
8. <email>john@email.com</email>
9. <street1>123 Main St.</street1>
10. <street2>Apt 3G</street2>
11. <city>Anytown</city>
12. <state>ONT</state>
13. <postal_code>55555</postal_code>
14. <country>NZ</country>
15. <custom_date>1970-07-14</custom_date>
16. <custom_field>He Likes Cheese</custom_field>
17. <customer_username>jdoe1970</customer_username>
18. <registered>Y</registered>
19. <custom_field_2>
20. <label>Marital Status</label>
21. <data>Single</data>
22. </custom_field_2>
23. ...
24. </customer>
25. <campaigns>
26. <campaign>
27. <id>1234567890123456</id>
28. <name>Widget Rewards</name>
29. <type>points</type>
30. <balance>1500</balance>
31. <cumulative>0</cumulative>
32. <last_transaction>2011-12-31</last_transaction>
33. <balance_coalition>1500</balance_coalition>
34. <cumulative_coalition>8350</cumulative_coalition>
35. <available_rewards>
36. <reward>
37. <id>678</id>
38. <description>Free Widget</description>
39. <needed_to_redeem>1000</needed_to_redeem>
40. <reward_id>A-345678</reward_id>
41. </reward>
42. <reward>
43. <id>753</id>
44. <description>Free bigger widget</description>
45. <needed_to_redeem>2500</needed_to_redeem>
46. </reward>
47. </available_rewards>
48. </campaign>
49. <campaign>
50. <id>0123456123456789</id>
51. <name>ACME Rewards</name>
52. <type>points</type>
53. <balance>1500</balance>
54. <cumulative>4500</cumulative>
55. <last_transaction>2011-12-31</last_transaction>
56. <balance_coalition>1500</balance_coalition>
57. <cumulative_coalition>8350</cumulative_coalition>
58. <available_rewards>
59. <reward>
60. <id>678</id>
61. <description>Free Widget</description>
62. <needed_to_redeem>1000</needed_to_redeem>
63. <reward_id>A-345678</reward_id>
64. </reward>
65. <reward>
66. <id>753</id>
67. <description>Free bigger widget</description>
68. <needed_to_redeem>2500</needed_to_redeem>
69. </reward>
70. </available_rewards>
71. </campaign>
72. </campaigns>
73. </response>

Notes:

• ALL campaigns that belong to a coalition will show the SAME balance. In the example above, both campaigns (stores) show the same <balance> however, the <cumulative_balance> at a store might be 0 (zero) if the points were earned in another store.

XML Response if no customer matches code or card_number given:

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

Error XML Response:

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