API DOCUMENTATION Last Update: Apr 2022

Manage Transaction Fields - Update

Update fields used when recording customer transactions:


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


  field   Example   Note
API 1.6 Required
user_id john1970 Required
user_api_key 1959caadac9b13dcb3 Required
type transaction_fields Required
action update Required
account_id greatwidgets Required
custom_field_#_label Item SKU optional
custom_field_#_show Y optional
custom_field_#_type Text See Note
custom_field_#_choices New|Used|Other optional
custom_field_#_activity_type record, redeem, all optional
web_update Y 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



  • Only users with proper permissions can access this call.
  • Multiple fields can be added at the same time.
  • [field_name]_type and [field_name]_unique will be ignored if the field to be updated already exists (as it should in an "update" API call -- however, it is allowed to be passed in case the update is done blindly without the ability to know if the field already exists or not, in which case it would be "added", and that requires the "type" to be set, and perhaps if that field is to be "unique" or not, since the these can only be set when a field is created.
  • If using this call as part of a web-based HTML form where users tick checkboxes to select which fields to show, the HTML form will only send back those fields whose boxes are checked. (ie: unchecking a box means that no data is sent back and is essentially the same as the option having never been given.) To solve that issue, either make sure to develop code to still send any "unchecked" field with its value set to "N", OR include the web_udate=Y option which will cause the API to treat any non-submitted choice (unchecked) as having been assigned the value of "N" (This works only on existing fields, because it assumes that those that are "missing" are those that are unchecked.)
  • If a field is received by the API to be updated and does not already exist, it will be created with any values provided (Default: Show=No, if it's not provided.) WARNING: This will NOT happen if a type is not provided, and you cannot change the type once it's set.
  • Field types are:
    • Text (up to 255 characters)
    • Number (max precision of 16 digits, with 5 decimal. ie: max value: 99,999,999,999.99999)
    • Monetary (max precision of 14 digits, with 2 decimal. ie: max value: 999,999,999,999.99)
    • Date ("datetime" stamp. Ex: 2012-01-01 14:45:04 )
    • Pick (Requires [field_name]_choices )
    • List (Requires [field_name]_choices )
  • Additional fields MUST have the following field_name structure:
    • "custom_field_#" where the "#" is any integer above 1
      (one of the default fields is "custom_field_1")
      • custom_field_2
      • custom_field_14
      • ...
  • NEW: Field "activity" types
    • record To use the field for accruals (positive transactions)
    • redeem To use the field for redemtions (negative transactions)
    • all To use the field for both, acrruals and redemptions.

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['account_id'] = 'greatwidgets';
  5. $data['type'] = 'transaction_fields';
  6. $data['action'] = 'update';
  7. $data['custom_field_1_label'] = 'SKU'
  8. $data['custom_field_2_show'] = 'N';
  9. $data['custom_field_6_label'] = 'New Field';
  10. $data['custom_field_6_show'] = 'Y';
  11. $data['custom_field_6_type'] = 'Text';
  12. $data['custom_field_6_activity_type'] = 'redeem';


Success XML Response (lists ONLY the custom fields added):

  1. <response status="success">
  2. <account>
  3. <account_id>test2009050502</account_id>
  4. <fields>
  5. <field>
  6. <name>custom_field_1</name>
  7. <label>ID</label>
  8. <show>Y</show>
  9. <type>Text</type>
  10. <unique>Yes</unique>
  11. </field>
  12. <field>
  13. <name>custom_field_2</name>
  14. <label>Tags</label>
  15. <show>N</show>
  16. <type>List</type>
  17. <choices>
  18. <choice>Tag A</choice>
  19. <choice>Tag B</choice>
  20. <choice>Tag C</choice>
  21. </choice>
  22. </field>
  23. <field>
  24. <name>custom_field_3</name>
  25. <label>Condition</label>
  26. <show>Y</show>
  27. <type>Pick</type>
  28. <choices>
  29. <choice>New</choice>
  30. <choice>Used</choice>
  31. <choice>Other</choice>
  32. </choice>
  33. </field>
  34. <field>
  35. <name>custom_field_4</name>
  36. <label>Expiration Date</label>
  37. <show>Y</show>
  38. <type>Date</type>
  39. </field>
  40. <field>
  41. <name>custom_field_5</name>
  42. <label>Kilograms</label>
  43. <show>Y</show>
  44. <type>Number</type>
  45. </field>
  46. <field>
  47. <name>custom_field_6</name>
  48. <label>New Field</label>
  49. <show>Y</show>
  50. <type>Text</type>
  51. <activity_type>redeem</activity_type>
  52. </field>
  53. </fields>
  54. </account>
  55. </response>



  • The <show> response indicates whether or not this field ought to be shown or not. Usually fields with "N" will have nothing in them. However, it is allowed to add content to any defined field through the API regardless of their <show> status.


Error XML Response:

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