Redemption Transaction

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:

Fields for Points-Based Campaigns:

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

Fields for Gift-Card Campaigns:

Fields for Buy-X-Get-One-Free / Membership Campaigns:

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

Fields for Events (Visits) Based Campaigns:

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

Fields for Earn-per-Event (Visits) Campaigns:

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

Points-Based Campaign - Pre-defined Reward:

1. $data['user_id'] = 'john1970';
2. $data['user_password'] = '1959caadac9b13dcb3';
3. $data['type'] = 'redeem';
4. $data['account_id'] = 'greatwidgets';
5. $data['code'] = '1234567890123456';
6. $data['campaign_id'] = '111234567890123456';
7. $data['reward_to_redeem'] = '98';
8. $data['authorization'] = 'Custom description';

Points-Based Campaign - Custom Points:

1. $data['user_id'] = 'john1970';
2. $data['user_password'] = '1959caadac9b13dcb3';
3. $data['type'] = 'redeem';
4. $data['account_id'] = 'greatwidgets';
5. $data['code'] = '1234567890123456';
6. $data['campaign_id'] = '111234567890123456';
7. $data['custom_points_redeem'] = '100';
8. $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.

1. $data['user_id'] = 'john1970';
2. $data['user_password'] = '1959caadac9b13dcb3';
3. $data['type'] = 'redeem';
4. $data['account_id'] = 'greatwidgets';
5. $data['code'] = '1234567890123456';
6. $data['campaign_id'] = '111234567890123456';
7. $data['custom_dollars_redeem'] = '9.95';
8. $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.

1. $data['user_id'] = 'john1970';
2. $data['user_password'] = '1959caadac9b13dcb3';
3. $data['type'] = 'redeem';
4. $data['account_id'] = 'greatwidgets';
5. $data['code'] = '1234567890123456';
6. $data['campaign_id'] = '111234567890123456';
7. $data['reward_to_redeem'] = '98';
8. $data['custom_points_redeem'] = '100';
9. $data['custom_dollars_redeem'] = '9.95';
10. $data['authorization'] = 'Custom description';

Gift Card Campaign:

1. $data['user_id'] = 'john1970';
2. $data['user_password'] = '1959caadac9b13dcb3';
3. $data['type'] = 'redeem';
4. $data['account_id'] = 'greatwidgets';
5. $data['code'] = '1234567890123456';
6. $data['campaign_id'] = '2234567890123456456';
7. $data['reward_to_redeem'] = '9.95';
8. $data['authorization'] = 'Custom description';

Buy-X-Get-One-Free Campaign:

1. $data['user_id'] = 'john1970';
2. $data['user_password'] = '1959caadac9b13dcb3';
3. $data['type'] = 'redeem';
4. $data['account_id'] = 'greatwidgets';
5. $data['code'] = '1234567890123456';
6. $data['campaign_id'] = '3334567890123456456';
7. $data['reward_to_redeem'] = '96';
8. $data['authorization'] = 'Custom description';

Events-Based Campaign:

1. $data['user_id'] = 'john1970';
2. $data['user_password'] = '1959caadac9b13dcb3';
3. $data['type'] = 'redeem';
4. $data['account_id'] = 'greatwidgets';
5. $data['code'] = '1234567890123456';
6. $data['campaign_id'] = '4444567890123456456';
7. $data['reward_to_redeem'] = '41';
8. $data['authorization'] = 'Custom description';

Earn-per-Event Campaign:

1. $data['user_id'] = 'john1970';
2. $data['user_password'] = '1959caadac9b13dcb3';
3. $data['type'] = 'redeem';
4. $data['account_id'] = 'greatwidgets';
5. $data['code'] = '1234567890123456';
6. $data['campaign_id'] = '55567890123456456';
7. $data['reward_to_redeem'] = '9.95';
8. $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:

1. <response status="success">
2. <receipt>
3. <account_name>Demo Business</account_name>
4. <agency>
5. <id>acmemktg</id>
6. <name>ACME Marketing</name>
7. <email>server@acmemarkting.com</email>
8. </agency>
9. <campaign>
10. <id>111234567890123456</id>
11. <name>Widget Rewards</name>
12. </campaign>
13. <customer>
14. <first_name>Jane</first_name>
15. <last_name>Doe</last_name>
16. <card_number>11112222</card_number>
17. <phone>555-5555</phone>
18. <email>jdoe@workemail.com</email>
19. <custom_field>She likes cheese</custom_field>
20. <custom_date>1970-07-14</custom_date>
21. </customer>
22. <transaction>
23. <id>1234</id>
24. <description>Optional note here</description>
25. <reward>
26. <id>98</id>
27. <points>100</points>
28. <description>Free Widget!</description>
29. </reward>
30. <custom>
31. <points>150</points>
32. </custom>
33. <monetary>
34. <amount>9.90</points>
35. <currency>USD</currency>
36. <points>1990</points>
37. </monetary>
38. <balance>
39. <points>4590</points>
40. <monetary>4.75</monetary>
41. <currency>USD</currency>
42. </balance>
43. <cumulative_balance>
44. <points>78390</points>
45. <monetary>43.50</monetary>
46. <currency>USD</currency>
47. </cumulative_balance>
48. </transaction>
49. </receipt>
50. </response>

For Gift Card Campaign:

1. <response status="success">
2. <receipt>
3. <account_name>Demo Business</account_name>
4. <agency>
5. <id>acmemktg</id>
6. <name>ACME Marketing</name>
7. <email>server@acmemarkting.com</email>
8. </agency>
9. <campaign>
10. <id>2234567890123456456</id>
11. <name>Gift Card</name>
12. </campaign>
13. <customer>
14. <first_name>Jane</first_name>
15. <last_name>Doe</last_name>
16. <card_number>11112222</card_number>
17. <phone>555-5555</phone>
18. <email>jdoe@workemail.com</email>
19. <custom_field>She likes cheese</custom_field>
20. <custom_date>1970-07-14</custom_date>
21. </customer>
22. <transaction>
23. <id>1234</id>
24. <deduct>
25. <amount>14.95</amount>
26. <currency>USD</currency>
27. <description>Optional note here</description>
28. </deduct>
29. <balance>
30. <amount>40.75</amount>
31. <currency>USD</currency>
32. </balance>
33. <cumulative_balance>
34. <amount>413.50</amount>
35. <currency>USD</currency>
36. </cumulative_balance>
37. </transaction>
38. </receipt>
39. </response>

For Events Campaign:

1. <response status="success">
2. <receipt>
3. <account_name>Demo Business</account_name>
4. <agency>
5. <id>acmemktg</id>
6. <name>ACME Marketing</name>
7. <email>server@acmemarkting.com</email>
8. </agency>
9. <campaign>
10. <id>4444567890123456456</id>
11. <name>Frequent Shopper</name>
12. </campaign>
13. <customer>
14. <first_name>Jane</first_name>
15. <last_name>Doe</last_name>
16. <card_number>11112222</card_number>
17. <phone>555-5555</phone>
18. <email>jdoe@workemail.com</email>
19. <custom_field>She likes cheese</custom_field>
20. <custom_date>1970-07-14</custom_date>
21. </customer>
22. <transaction>
23. <id>1234</id>
24. <description>Optional note here</description>
25. <reward>
26. <id>41</id>
27. <amount>9</amount>
28. <description>Free Widget!</description>
29. </reward>
30. <balance>
31. <events>12</events>
32. </balance>
33. <cumulative_balance>
34. <events>25</events>
35. </cumulative_balance>
36. </transaction>
37. </receipt>
38. </response>

For Earn-per-Event Campaign:

1. <response status="success">
2. <receipt>
3. <account_name>Demo Business</account_name>
4. <agency>
5. <id>acmemktg</id>
6. <name>ACME Marketing</name>
7. <email>server@acmemarkting.com</email>
8. </agency>
9. <campaign>
10. <id>55567890123456456</id>
11. <name>GateKeeper Rewards</name>
12. </campaign>
13. <customer>
14. <first_name>Jane</first_name>
15. <last_name>Doe</last_name>
16. <card_number>11112222</card_number>
17. <phone>555-5555</phone>
18. <email>jdoe@workemail.com</email>
19. <custom_field>She likes cheese</custom_field>
20. <custom_date>1970-07-14</custom_date>
21. </customer>
22. <transaction>
23. <id>1234</id>
24. <deduct>
25. <amount>14.95</amount>
26. <currency>USD</currency>
27. <description>Optional note here</description>
28. </deduct>
29. <balance>
30. <amount>22.50</amount>
31. <currency>USD</currency>
32. </balance>
33. <cumulative_balance>
34. <amount>45.00</amount>
35. <currency>USD</currency>
36. </cumulative_balance>
37. </transaction>
38. </receipt>
39. </response>

For Buy-X-Get-One-Free Campaign:

1. <response status="success">
2. <receipt>
3. <account_name>Demo Business</account_name>
4. <agency>
5. <id>acmemktg</id>
6. <name>ACME Marketing</name>
7. <email>server@acmemarkting.com</email>
8. </agency>
9. <campaign>
10. <id>3334567890123456456</id>
11. <name>Frequent Buyer Rewards</name>
12. </campaign>
13. <customer>
14. <first_name>Jane</first_name>
15. <last_name>Doe</last_name>
16. <card_number>11112222</card_number>
17. <phone>555-5555</phone>
18. <email>jdoe@workemail.com</email>
19. <custom_field>She likes cheese</custom_field>
20. <custom_date>1970-07-14</custom_date>
21. </customer>
22. <transaction>
23. <id>1234</id>
24. <description>Optional note here</description>
25. <reward>
26. <service_product>Books</service_product>
27. <deduct>10</deduct>
28. </reward>
29. <balances>
30. <item>
31. <name>Books</name>
32. <current>14</current>
33. <cumulative>14</cumulative>
34. </item>
35. <item>
36. <name>Coffees & Teas</name>
37. <current>6</current>
38. <cumulative>43</cumulative>
39. </item>
40. <item>
41. <name>Cakes & Cookies</name>
42. <current>2</current>
43. <cumulative>12</cumulative>
44. </item>
45. ...
46. </balances>
47. </transaction>
48. </receipt>
49. </response>

Error XML Response:

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