Manage Transaction Fields - Update

Update fields used when recording customer transactions:

Headers

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

NOTE:

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

• 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")
    Example:
    • 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>

NOTE:

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