API DOCUMENTATION Last Update: Mar 28, 2022

BuyX Campaign Items List

Returns a list of the items that can be accumulated for the given "Buy X Get One Free" campaign.


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


  field   Example   Note
API 1.5 Required
user_id john1970 Required
user_api_key 1959caadac9b13dcb3 Required
account_id greatwidgets Required
type buyx_items_list Required
campaign_id 1111222233334444 Required

service_product or


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)

searchValue Coffee (service_product)or
51 (reward_id) or
10 (buy_amount)

service_product or

sortOrder DESC or


offset 0 Optional
length 10 Optional
Output Format:
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



  • 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:
      • service_product - For the text description of the items accumulated
      • reward_id - the Reward ID of the item.
      • buy_amount - The amount of times the item has to be purchased to earn a free one.


Example PHP Request:

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'] = '1959caadac9b13dcb3';
  4. $data['type'] = 'buyx_items_list';
  5. $data['account_id'] = 'greatwidgets';
  6. $data['campaign_id'] = '1111222233334444';
  7. $data['searchField'] = 'service_product';
  8. $data['searchValue'] = 'Coffee';
  9. $data['searchOper'] = 'cn';
  10. $data['sortField'] = 'service_product';
  11. $data['sortOrder'] = 'ASC';
  12. $data['offset'] = '30';
  13. $data['length'] = '10';


Success XML Response:

  1. <response status="success">
  2. <campaign>
  3. <id>1111222233334444</id>
  4. <name>Store Rewards!</name>
  5. </campaign>
  6. <pagination>
  7. <total>56</total>
  8. <offset>30</offset>
  9. <pagination>
  10. <buyx_items>
  11. <item>
  12. <id>345</id>
  13. <description>Coffees and Lattes</description>
  14. <quantity>8</quantity>
  15. </item>
  16. <item>
  17. <id>494</id>
  18. <description>Blended Drinks</description>
  19. <quantity>12</quantity>
  20. <reward_id>12398749834</reward_id>
  21. </item>
  22. ...
  23. </buyx_items>
  24. </response>


  • The "quantity" is the amount of the item needed to be purchased before the next one is free – Not a customer's balance.
  • When identifying the item (or "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 item_identifier field.


Error XML Response:

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