Batch Transactions

Record a batch of transactions for a customer account, including redemptions.

Headers

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

Fields common to all campaign types:

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.
• If apply_ratio is given as "yes":
  • Points Campaigns:
    • Add transaction: amount = monetary value (which will be converted into points)
    • Redemptions: amount = reward unique_id or reward_id (which will be converted into points)
  • Giftcard Campaigns:
    • (apply_ratio not applicable.)
  • Event Campaigns:
    • Add transaction: amount = number of events.
    • Redemptions: amount = reward unique_id or reward_id (which will be converted into accumulated events to be deducted)
  • Earned Campaigns:
    • Add transaction: amount = events (which will be converted into monetary value)
    • Redemptions: amount = monetary value.
  • BuyX Campaings: amount given will be assumed to be:
    • Purchases: amount = number of items purchased
    • Redemptions: amount = number of items redeemed (which will be converted into accumulated items to be deducted)

• Unless there's a good reason, don't include the 'allow-undo' = 'yes' directive, otherwise every batch will be listed as an "undo-able" entry in the Manage Customer Records section of the Dashboard.
• Dates should be provided in ISO format: YYYY-MM-DD (ISO-8601)

Fields for Points-Based Campaigns:

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.
• If promo_id is used, and multiple given and separated by commas, DO NOT USE comma as delimiter (duh!)

Fields for Gift-Card Campaigns:

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.

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

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.

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

Fields for Events (Visits) Based Campaigns:

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.

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

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 PHP Request for Points-Based Campaign:

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

1. $data['API'] = '1.5';
2. $data['user_id'] = 'john1970';
3. $data['user_api_key'] = '1959caadac9a8f7e42938a7b13dcb3';
4. $data['account_id'] = 'greatwidgets';
5. $data['type'] = 'batch_transactions';
6. $data['delimiter'] = 'pipe';
7. $data['apply_ratio'] = 'yes';
8. $data['allow-undo'] = 'yes';
9. $data['visits_header_1'] = 'campaign_id';
10. $data['visits_header_2'] = 'code';
11. $data['visits_header_3'] = 'redeemed';
12. $data['visits_header_4'] = 'amount';
13. $data['visits_header_5'] = 'date';
14. $data['visits_header_6'] = 'custom_field_3';
15. $data['Visits_Data'] = '
16. 4638472975924871|12121|N|14,95|2010-03-15|API test import 1
17. 4638472975924871|12121|N|50|2010-03-15|API test import 2
18. 4638472975924871|12121|N|34.67|2010-03-15|API test import 3
19. 4638472975924871|12121|N|0,50|2010-03-15|API test import 4
20. 4638472975924871|12121|N|.75|2010-03-15|API test import 5
21. 4638472975924871|12121|N|2.00|2010-03-15|API test import 6
22. 4638472975924871|12121|Y|1500|2010-03-15|API test redeem 1
23. ';

Success XML Response:

1. <response status="success">
2. <batch status="all_imported">
3. <transactions>7</transactions>
4. </batch>
5. </response>

Error XML Response:

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