Customer Balance and Transaction History

Returns a customer's balance and transaction history for a particular campaign.

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.

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

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_balance';
4. $data['account_id'] = 'greatwidgets';
5. $data['campaign_id'] = 'Store Rewards';
6. $data['code'] = '1234567890123456';
7. or
8. $data['card_number'] = '29374856';

Success XML Response (Points-Based Campaign):

1. <response status="success">
2. <campaign>
3. <campaign_id>4857302875023023</campaign_id>
4. <campaign_type>points</campaign_type>
5. <campaign_name>Store_Rewards</campaign_name>
6. <customer>
7. <code>1234567890123456</code>
8. <balance>1500</balance>
9. <last_transaction>2011-12-15</last_transaction>
10. <last_redemption>2011-12-31</last_redemption>
11. <transactions>
12. <transaction>
13. <id>4056</id>
14. <date>2011-12-15</date>
15. <amount>20000</amount>
16. <orig_amount>200</orig_amount>
17. <redeemed>N</redeemed>
18. <authorization>Purchased Item</authorization>
19. <user_name>employee1</user_name>
20. </transaction>
21. <transaction>
22. <id>4097</id>
23. <date>2011-21-31</date>
24. <amount>-15000</amount>
25. <redeemed>Y</redeemed>
26. <authorization>Redeemed Item</authorization>
27. <user_name>employee2</user_name>
28. </transaction>
29. ...
30. </transactions>
31. </customer>
32. </campaign>
33. </response>

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

1. <response status="success">
2. <campaign>
3. <campaign_id>4857302875023023</campaign_id>
4. <campaign_type>points</campaign_type>
5. <campaign_name>Store_Rewards</campaign_name>
6. <reward_ratio>10</reward_ratio>
7. <customer>
8. <code>1234567890123456</code>
9. <balance>1500</balance>
10. <equivalent_cash_balance>1.50</equivalent_cash_balance>
11. <equivalent_cash_currency>Euro</equivalent_cash_currency>
12. <equivalent_cash_glyph>&euro;</equivalent_cash_glyph>
13. <last_transaction>2011-12-15</last_transaction>
14. <last_redemption>2011-12-31</last_redemption>
15. <transactions>
16. <transaction>
17. <id>4056</id>
18. <date>2011-03-15</date>
19. <amount>20000</amount>
20. <orig_amount>200</orig_amount>
21. <redeemed>N</redeemed>
22. <authorization>Purchased Item</authorization>
23. <user_name>employee1</user_name>
24. </transaction>
25. <transaction>
26. <id>4097</id>
27. <date>2011-12-31</date>
28. <amount>-50-0</amount>
29. <equivalent_cash_amount>-5.00</equivalent_cash_amount>
30. <redeemed>Y</redeemed>
31. <authorization>Redeemed Item</authorization>
32. <user_name>employee2</user_name>
33. </transaction>
34. ...
35. </transactions>
36. </customer>
37. </campaign>
38. </response>

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

1. <response status="success">
2. <campaign>
3. <campaign_id>4857302875023023</campaign_id>
4. <campaign_type>points</campaign_type>
5. <campaign_name>Store_Rewards</campaign_name>
6. <customer>
7. <code>1234567890123456</code>
8. <balance>1500</balance>
9. <equivalent_cash_balance>1.50</equivalent_cash_balance>
10. <equivalent_cash_currency>Euro</equivalent_cash_currency>
11. <equivalent_cash_glyph>&euro;</equivalent_cash_glyph>
12. <last_transaction>2011-12-15</last_transaction>
13. <last_redemption>2011-12-31</last_redemption>
14. <transactions>
15. <transaction>
16. <id>4056</id>
17. <date>2011-12-15</date>
18. <amount>20000</amount>
19. <orig_amount>200.00</orig_amount>
20. <redeemed>N</redeemed>
21. <authorization>Purchased Item</authorization>
22. <user_name>employee1</user_name>
23. <custom_field_2>
24. <label>quantity</label>
25. <data>2</data>
26. </custom_field_2>
27. </transaction>
28. <transaction>
29. <id>4097</id>
30. <date>2011-12-31</date>
31. <amount>-5000</amount>
32. <redeemed>Y</redeemed>
33. <authorization>Redeemed Item</authorization>
34. <user_name>employee2</user_name>
35. <custom_field_2>
36. <label>quantity</label>
37. <data>1</data>
38. </custom_field_2>
39. </transaction>
40. ...
41. </transactions>
42. </customer>
43. </campaign>
44. </response>

Success XML Response (Gift Card Campaign):

1. <response status="success">
2. <campaign>
3. <campaign_id>57203576293875493</campaign_id>
4. <campaign_type>giftcard</campaign_type>
5. <campaign_name>Gift Basket</campaign_name>
6. <customer>
7. <code>1234567890123456</code>
8. <balance>36.75</balance>
9. <last_transaction>2011-12-15</last_transaction>
10. <last_redemption>2011-12-31</last_redemption>
11. <transactions>
12. <transaction>
13. <id>4056</id>
14. <date>2011-12-15</date>
15. <amount>40</amount>
16. <redeemed>N</redeemed>
17. <authorization>Cash Added</authorization>
18. <user_name>employee2</user_name>
19. </transaction>
20. <transaction>
21. <id>4097</id>
22. <date>2011-12-31</date>
23. <amount>-3.25</amount>
24. <redeemed>Y</redeemed>
25. <authorization>Cash Redeemed</authorization>
26. <user_name>employee2</user_name>
27. </transaction>
28. ...
29. </transactions>
30. </customer>
31. </campaign>
32. </response>

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

1. <response status="success">
2. <campaign>
3. <campaign_id>53485702387562034</campaign_id>
4. <campaign_type>buyx</campaign_type>
5. <campaign_name>Club Fantastic</campaign_name>
6. <customer>
7. <code>1234567890123456</code>
8. <balances>
9. <item>
10. <name>Coffees</name>
11. <balance>14</balance>
12. <earned>1</earned>
13. </item>
14. <item>
15. <name>Cakes</name>
16. <balance>7</balance>
17. <earned>0</earned>
18. </item>
19. <item>
20. <name>Books</name>
21. <balance>2</balance>
22. <earned>0</earned>
23. </item>
24. </balances>
25. <last_transaction>2011-12-15</last_transaction>
26. <last_redemption>2011-12-31</last_redemption>
27. <transactions>
28. <transaction>
29. <id>4056</id>
30. <date>2011-12-15</date>
31. <service_product>Coffees</service_product>
32. <amount>12</amount>
33. <redeemed>N</redeemed>
34. <authorization>Purchased Items</authorization>
35. <user_name>employee1</user_name>
36. </transaction>
37. <transaction>
38. <id>4097</id>
39. <date>2011-12-31</date>
40. <service_product>Cakes</service_product>
41. <amount>1</amount>
42. <redeemed>Y</redeemed>
43. <authorization>Redeemed Items</authorization>
44. <user_name>employee1</user_name>
45. </transaction>
46. ...
47. </transactions>
48. </customer>
49. </campaign>
50. </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):

1. <response status="success">
2. <campaign>
3. <campaign_id>683979284679238</campaign_id>
4. <campaign_type>events</campaign_type>
5. <campaign_name>Frequent Shopper</campaign_name>
6. <customer>
7. <code>1234567890123456</code>
8. <balance>23</balance>
9. <last_transaction>2011-12-15</last_transaction>
10. <last_redemption>2011-12-31</last_redemption>
11. <transactions>
12. <transaction>
13. <id>4056</id>
14. <date>2011-12-15</date>
15. <amount>1</amount>
16. <redeemed>N</redeemed>
17. <authorization>Visit Note</authorization>
18. <user_name>employee1</user_name>
19. <transaction>
20. </transaction>
21. <id>4097</id>
22. <date>2011-12-31</date>
23. <amount>-10</amount>
24. <redeemed>Y</redeemed>
25. <authorization>Redeemed Reward</authorization>
26. <user_name>employee2</user_name>
27. </transaction>
28. ...
29. </transactions>
30. </customer>
31. </campaign>
32. </response>

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

1. <response status="success">
2. <campaign>
3. <campaign_id>325702938572039</campaign_id>
4. <campaign_type>earned</campaign_type>
5. <campaign_name>Referral Rewards</campaign_name>
6. <customer>
7. <code>1234567890123456</code>
8. <balance>105.00</balance>
9. <last_transaction>2011-12-15</last_transaction>
10. <last_redemption>2011-12-31</last_redemption>
11. <transactions>
12. <transaction>
13. <id>4056</id>
14. <date>2011-12-15</date>
15. <amount>4.50</amount>
16. <redeemed>N</redeemed>
17. <authorization>Event Earning</authorization>
18. <user_name>employee1</user_name>
19. </transaction>
20. <transaction>
21. <id>4097</id>
22. <date>2011-12-31</date>
23. <amount>-29.95</amount>
24. <redeemed>Y</redeemed>
25. <authorization>Redeemed reward</authorization>
26. <user_name>employee1</user_name>
27. </transaction>
28. ...
29. </transactions>
30. </customer>
31. </campaign>
32. </response>

Error XML Response:

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