API DOCUMENTATION Last Update: Apr 2022

Update Customer Information

Update a customer account with new information.


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


  field   Example   Note
user_id john1970 Required
user_password 1959caadac9b13dcb3 Required
type record_customer Required
customer_action edit Required
account_id greatwidgets Required
code 89898989898989 Optional
new_code Yes Optional
card_number 1212121212 Optional
card_number_generate (# of digits) Optional
first_name John Optional
last_name Doe Optional
phone 555-555-2455 Optional
email test@email.com Optional
street1 123 Main St. Optional
street2 Apt 3G Optional
city Anytown Optional
state ZZ Optional
postal_code 55555 Optional
country NZ Optional
custom_date 1970-07-14 Optional
custom_field John likes cheese. Optional
customer_username jdoe1970 Optional
customer_password ilovecheese Optional
customer_PIN 1234 Optional
custom_field_## 1kg Emental Cheese


2012.07.28 22:59:59



send_no_email true Optional or
don't include.
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



  • 'code' is required to update an EXISTING customer as it is the internal ID for the customer.
  • If it is NOT included, a NEW customer will be created, and the API response will return a randomly generated 16-digit unique id as the 'code'.
  • If the code is given, but it matches NO existing customer, a NEW customer will be created with the information given.
  • In either case, if your application can, record the 'code' transmitted back, and include it with all transactions associated with this customer. If not, don't worry. You can always query the API for the 'code' associated with a card_number for future transactions recording.
  • If only a card_number is passed on an "edit" call, it will first try to match it to an existing card_number. If there's multiple matches, it will return an error.  If there's a single match, it will assume that record to be the correct one, and proceed with the edit, and return the pre-existing "code" of the record that was matched and modified.  If no matching card_number is found, it will attempt one last match at the "code", and if it finds a single "code" that matches the card_number, then it will update that record and return that "code". (In both cases, "edit" also means that whatever card_number existed will be replaced by the one used in this API call.)   If there's no match, as mentioned above, it will create a new record and return a random 16-digit "code". 
  • If you want the program to generate a random unique card number, then include the card_number_generate field with the number of digits for the card number to be generated.
  • All optional fields are optional individually, but at least ONE must be passed along.
  • If the customer_action tag is set to edit, and the customer data matches an existing record, the existing record will be updated with the new information and a status of "update" will be returned in the response. If instead, no match is found, a new customer will be created with the information passed, and the status returned will be "new"
  • The 'custom_date' must be in YYYY-MM-DD format. (Any other format cannot be resolved without further context. Ex: 04-03-2010 could be either April 3rd or 4th of March. Don't even get us started on inputs like 04-06-05... What the heck is THAT?. Also this format conforms to ISO-8601.)
  • The customer_username is an API-specific field made available for custom applications. It cannot be defined or edited in the web interface.
  • The customer_password field is made available for custom applications such as a customer"hotsite". It can be defined or edited in the web interface.
  • The customer_PIN is an API-specific field made available for custom applications such as a physical terminal. It cannot be defined or edited in the web interface.
  • To automatically add an amount to a customer's account in the campaign specified above, when using this call, the optional auto_add parameter lets you specify the amount of points, visits, dollars, or name of product or service, depending on the campaign type, to add. For example, as a thank-you bonus for signing-up, you would user auto_add = "25" (which will add 25 points to the customer's account balance.)
  • The send_no_email is an API-specific field that if included will suppress the normal email that is generated and sent to the account owner letting them know about the new customer and their information (for example to send a plastic card to.)
  • custom_field_## must be first defined by through the Custom Fields - Create API call, and can be listed by first calling the Custom Fields - List API call. The content of a custom field must match its type. So for example, if a custom field expects a date / time stamp, it will reject with an error anything but that format.


Example PHP Request:

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

  1. $data['user_id'] = 'john1970';
  2. $data['user_password'] = '1959caadac9b13dcb3';
  3. $data['type'] = 'record_customer';
  4. $data['customer_action'] = 'edit';
  5. $data['account_id'] = 'greatwidgets';
  6. $data['code'] = '89898989898989';
  7. $data['card_number'] = '1212121212';
  8. or: $data['card_number_generate'] = 10; // for 10-digit number.
  9. $data['first_name'] = 'John';
  10. $data['last_name'] = 'Doe';
  11. $data['phone'] = '555-555-2455';
  12. $data['email'] = 'test@yourdomain.com';
  13. $data['custom_date'] = '1970-07-14';
  14. $data['street1'] = '123 Main St.';
  15. $data['street2'] = 'Apt 3G';
  16. $data['city'] = 'Anytown';
  17. $data['state'] = 'ZZ';
  18. $data['postal_code'] = '55555';
  19. $data['country'] = 'NZ';
  20. $data['customer_username'] = 'jdoe1970';
  21. $data['customer_password'] = 'ilovecheese';
  22. $data['customer_PIN'] = '1234';
  23. $data['custom_field_2'] = 'Single';


Success XML Response (Update Customer):

  1. <response status="success">
  2. <customer status="update">
  3. <code>1234567890123456</code>
  4. //only when card_number_generate is set:
  5. <card_number>1234567890</card_number>
  6. </customer>
  7. </response>


Error XML Response:

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