This document contains examples of typical use cases for the Customers API. These examples demonstrate calls to the SOAP interface and are provided as is.
Full API documentation is available here.
The following examples demonstrate calls to the Customers API in Java.
These examples assume the use of a generated XML web service client. To generate such a client, a tool such as wsdl2java can be used. A detailed description on this tool can be found on the Apache Web Services website - you will need to point this program at your site's Customers API endpoint. A detailed description of how to generate a web service client is beyond the scope of this document.
Note that these examples include minimal or no error handling. Any API callers are expected to handle errors appropriately.
// Instantiate the web service proxy
ISAMSCustomersAPI service = new ISAMSCustomersAPI();
// User to authenticate with.
String username = "Testing";
// Corresponding password to authenticate with.
String password = "Sup94zex";
// Authenticate.
ApiResponse authenticationResponse = service.authenticate(username, password);
String token = authenticationResponse.getMessage();
// Customer ID of the required customer.
int customerID = 5100;
// Retrieve the customer.
CustomerApiResponse retrieveResponse =
service.retrieveCustomer(token, customerID);
// Examine the CustomerApiResponse for our customer.
if (!retrieveResponse.isSuccess() || retrieveResponse.getData()[0] == null) {
System.out.printf("Failed to retrieve customer: %s", customerID);
} else {
// Extract the customer from the response.
Customer customer = retrieveResponse.getData()[0];
}
// Instantiate the web service proxy.
ISAMSCustomersAPI service = new ISAMSCustomersAPI();
// User to authenticate with.
String username = "Testing";
// Corresponding password to authenticate with.
String password = "Sup94zex";
// Authenticate.
ApiResponse authResponse = service.authenticate(username, password);
String token = authResponse.getMessage();
// List all customer IDs in the provided interest group.
IntegerArrayApiResponse listByInterestGroup =
service.listCustomersByInterestGroup(token, "Interest Group");
for (int customerID : listByInterestGroup.getData()){
System.out.println(customerID);
}
// List all customer IDs.
IntegerArrayApiResponse customerListing = service.listCustomers(token);
for (int customerID : customerListing.getData()){
System.out.println(customerID);
}
// Instantiate the web service proxy.
ISAMSCustomersAPI service = new ISAMSCustomersAPI();
// User to authenticate with.
String username = "Testing";
// Corresponding password to authenticate with.
String password = "Sup94zex";
// Authenticate and retrieve authentication token.
ApiResponse authResponse = service.authenticate(username, password);
String token = authResponse.getMessage();
// List the customer IDs of all customers using Gmail.
IntegerArrayApiResponse searchByEmail =
service.searchCustomers(token, "gmail.com", "", "", "", "", "", "");
for (int customerID : searchByEmail.getData()){
System.out.println(customerID);
}
// List the customer IDs of all customers with an Australian shipping address.
IntegerArrayApiResponse searchByShippingCountry =
service.searchCustomers(token, "", "", "", "", "AUS", "", "");
for (int customerID : searchByShippingCountry.getData()){
System.out.println(customerID);
}
// List the customer IDs of all customers with 'Brad' in their name, who have
// a billing address containing 'Auckland'.
IntegerArrayApiResponse searchByNameAndBillingAddress =
service.searchCustomers(token, "", "Brad", "", "", "", "Auckland", "");
for (int customerID : searchByNameAndBillingAddress.getData()){
System.out.println(customerID);
}
// Instantiate the web service proxy.
ISAMSCustomersAPI service = new ISAMSCustomersAPI();
// User to authenticate with.
String username = "Testing";
// Corresponding password to authenticate with.
String password = "Sup94zex";
// Authenticate and retrieve authentication token.
ApiResponse authResponse = service.authenticate(username, password);
String token = authResponse.getMessage();
// Create a Customer object for the new customer.
Customer customer = new Customer();
customer.setID(0); // ID must be zero to create a customer
customer.setForeignIdentity("ForeignIdentity001");
customer.setEmail("[email protected]");
customer.setTitle("Mr.");
customer.setFirstName("Firstname");
customer.setLastName("Lastname");
customer.setPhone("8675309");
customer.setFax("5551212");
customer.setMobile("0221234567");
customer.setPassword("qwerty1");
customer.setProtected(false);
customer.setLpmStatus(1); // Active LPM account
customer.setSmsStatus(1); // Receives SMS marketing
customer.setEmailFormat("HTML");
customer.setInterestGroups(new String[] { "Gadgets", "Widgets" });
CustomerAccount account = new CustomerAccount();
account.setAccountID("55");
account.setAccountName("Lastname Gadgets");
account.setAccountType("Gadgets Distributor");
account.setDiscount(5); // 5% sitewide discount
account.setFreeFreight(false);
customer.setAccount(account);
CustomerNote note = new CustomerNote();
note.setDisplayLevel(2); // Admin only
note.setNote("Added customer account");
customer.setNotes(new CustomerNote[] { note });
NameValuePair attribute = new NameValuePair();
attribute.setName("Reward points");
attribute.setValue("100");
customer.setAttributes(new NameValuePair[] { attribute });
CustomerAddress billing = new CustomerAddress();
billing.setType("Billing");
billing.setTitle("Prof.");
billing.setFirstName("Firstname");
billing.setLastName("Lastname");
billing.setStreet("123 Test Street");
billing.setSuburb("Greenpark");
billing.setCity("Christchurch");
billing.setCompany("Fancy Gadgets Inc.");
billing.setState("Canterbury");
billing.setCountry("NZL");
billing.setPostcode("1111");
billing.setExtraInfomation("Extra billing information");
billing.setContactPhone("61 1 9988 7766");
CustomerAddress shipping = new CustomerAddress();
shipping.setType("Shipping");
shipping.setTitle("Dr.");
shipping.setFirstName("Someone");
shipping.setLastName("Else");
shipping.setStreet("1 Fake Avenue");
shipping.setSuburb("Fancyville");
shipping.setCity("Brisbane");
shipping.setCompany("Widgets 'n' Things");
shipping.setState("QLD");
shipping.setCountry("AUS");
shipping.setPostcode("9999");
shipping.setExtraInfomation("Extra shipping information");
shipping.setContactPhone("61 9 1122 3344");
customer.setAddresses(new CustomerAddress[] { billing, shipping });
customer.setWebsites(new int[] { 1 }); // Linked to website ID 1
// Add the customer to the system.
service.updateCustomer(token, customer);
Note: The recommended method for modifying customer data is retrieving a Customer, modifying the customer as required, then updating the modified customer. This ensures that no other customer data will be unintentionally changed in the update.
// Instantiate the web service proxy.
ISAMSCustomersAPI service = new ISAMSCustomersAPI();
// User to authenticate with.
String username = "Testing";
// Corresponding password to authenticate with.
String password = "Sup94zex";
// Authenticate and retrieve authentication token.
ApiResponse authResponse = service.authenticate(username, password);
String token = authResponse.getMessage();
// Customer ID of the customer to update.
int customerID = 5100;
// Retrieve customer data.
CustomerApiResponse retrieveResponse =
service.retrieveCustomer(token, customerID);
// Examine the CustomerApiResponse for our customer.
if (!retrieveResponse.isSuccess() || retrieveResponse.getData().length == 0) {
System.out.printf("Failed to retrieve customer ID: %s", customerID);
} else {
// Extract the customer from the response.
Customer customer = retrieveResponse.getData()[0];
// Update of the Customer's data as required.
customer.setTitle("Dr.");
// Update the customer.
service.updateCustomer(token, customer);
}
// Instantiate the web service proxy. ISAMSCustomersAPI service = new ISAMSCustomersAPI(); // User to authenticate with. String username = "Testing"; // Corresponding password to authenticate with. String password = "Sup94zex"; // Authenticate and retrieve authentication token. ApiResponse authResponse = service.authenticate(username, password); String token = authResponse.getMessage(); // Customer ID of the customer to delete. int customerID = 5100; // Delete the customer from the system. service.deleteCustomer(token, customerID);
// Instantiate the web service proxy.
ISAMSCustomersAPI service = new ISAMSCustomersAPI();
// User to authenticate with.
String username = "Testing";
// Corresponding password to authenticate with.
String password = "Sup94zex";
// Authenticate and retrieve authentication token.
ApiResponse authResponse = service.authenticate(username, password);
String token = authResponse.getMessage();
// Customer ID of the customer whose password is to be reset.
int customerID = 5100;
// Website ID of the website that will be used to perform the password reset.
int websiteID = 1;
// Retrieve password reset information.
NVPApiResponse resetResponse =
service.retrievePasswordResetUrl(token, customerID, websiteID);
NameValuePair[] data = resetResponse.getData();
if (resetResponse.isSuccess()) {
// The customer should visit this URL to reset their password.
String url = "";
for (NameValuePair nvp : data) {
if (nvp.getName().equals("url")) {
url = nvp.getValue();
break;
}
}
System.out.printf("Use %s to reset your password", url);
// A site's configuration may require an additional code when a
// customer resets their password. If a code is included in the
// response, the customer will need to enter it when visiting the
// password reset URL.
String code = "";
for (NameValuePair nvp : data) {
if (nvp.getName().equals("code")) {
code = nvp.getValue();
break;
}
}
if (!code.equals("")) {
System.out.printf(
"You will need to enter the following code: %s", code
);
}
} else {
System.out.printf(
"Failed to retrieve password reset URL for customer ID: %s",
customerID
);
}