Orders API Examples - Java

Overview

This document contains examples of typical use cases for the Orders API. These examples demonstrate calls to the SOAP interface and are provided as is.

Full API documentation is available here.

Requirements

The following examples demonstrate calls to the Orders 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 Orders API endpoint. A detailed description of how to generate a web service client is beyond the scope of this document.

Examples

Note that these examples include minimal or no error handling. Any API callers are expected to handle errors appropriately.

Retrieve a single order's details

// Instantiate the web service proxy
OrdersAPISoapClient orderAPI = new OrdersAPISoapClient();

// User and password to authenticate with.
String username = "Testing";
String password = "Sup94zex";

// Authenticate and retrieve authentication token.
ApiResponse authResponse = orderAPI.authenticate(username, password);
String securityToken = authResponse.getMessage();

// Order ID of the required order.
int orderID = 10001;

// Retrieve the order.
OrderApiResponse response = orderAPI.retrieveOrder(securityToken, orderID);

// Examine the OrderApiResponse for our order.
if (!response.isSuccess() || response.getData()[0] == null) {
	System.out.printf("Failed to retrieve order: %s", orderID);
} else {
	// Extract the order from the response.
	Order order = response.getData()[0];
}

Create a new order

// Instantiate the web service proxy
OrdersAPISoapClient orderAPI = new OrdersAPISoapClient();

// User and password to authenticate with.
String username = "Testing";
String password = "Sup94zex";

// Authenticate and retrieve authentication token.
ApiResponse authResponse = orderAPI.authenticate(username, password);
String securityToken = authResponse.getMessage();

// Create a new order.
OrderApiResponse retrieveResponse = orderAPI.createOrder(securityToken);

// Examine the OrderApiResponse for our order.
if (!retrieveResponse.isSuccess() || retrieveResponse.getData()[0] == null) {
	System.out.println("Failed to create new order.");
} else {
	// Extract the new order from the response.
	Order order = retrieveResponse.getData()[0];
	System.out.println("New order ID: " + order.getID());
}

Add an item to an order.

// Instantiate the web service proxy
OrdersAPISoapClient orderAPI = new OrdersAPISoapClient();

// User and password to authenticate with.
String username = "Testing";
String password = "Sup94zex";

// Authenticate and retrieve authentication token.
ApiResponse authResponse = orderAPI.authenticate(username, password);
String securityToken = authResponse.getMessage();

int orderID = 10522;
string barcode = "BAR123";
int quantity = 1;

// Add an order item
ApiResponse response = 
	orderAPI.addOrderItem(securityToken, orderID, barcode, quantity);

// Examine the ApiResponse..
if (response.isSuccess()) {
	System.out.println("Added new order item.");
} else {
	System.out.println("Failed to add new order item.");
}

Import an order into the system

// Instantiate the web service proxy
OrdersAPISoapClient orderAPI = new OrdersAPISoapClient();

// User and password to authenticate with.
String username = "Testing";
String password = "Sup94zex";

// Authenticate and retrieve authentication token.
ApiResponse authResponse = orderAPI.authenticate(username, password);
String securityToken = authResponse.getMessage();

// Address data
CustomerAddress address = new CustomerAddress();
address.setFirstName("FirstName");
address.setLastName("LastName");
address.setStreet("Street");
address.setSuburb("Suburb");
address.setCity("City");
address.setCompany("Company");
address.setState("State");
address.setCountry("NZL");
address.setPostcode("1111");
address.setExtraInformation("ExtraInformation");

// Item data
OrderItem orderitem = new OrderItem();
orderitem.setProductItem(5);
orderitem.setQuantity(1);
orderitem.setStatusCode(OrderItemStatus.UNORDERED);
orderitem.setUnitPrice(new BigDecimal(20.0));

// Item Personalisation
ItemPersonalisation personalisation = new ItemPersonalisation();
personalisation.setPrice(new BigDecimal(10.0));
personalisation.setAdditionalData("<extraInfo>Custom Info</extraInfo>");

NameValuePair composition = new NameValuePair();
composition.setName("Colour");
composition.setValue("Red");

PersonalisedComponent component = new PersonalisedComponent();
component.setType("Name");
component.setValue("John Doe");
component.setComposition(new NameValuePair[] {composition});

personalisation.setComponent(new PersonalisedComponent[] {component});
orderitem.setPersonalisation(personalisation);

NameValuePair attribute = new NameValuePair();
attribute.setName("Attribute Name");
attribute.setValue("Attribute Value");

// New order to import.
Order order = new Order();
order.setPhone("1234567");
order.setEmail("[email protected]");
order.setStatus(OrderStatus.INITIATED);
order.setAdminReference("Reference");
order.setCustomerReference("Customer Reference");
order.setCurrency("NZD");
order.setFreight(new BigDecimal(10.0));
order.setFreightDiscount(new BigDecimal(0.0));
order.setOrderBasedDiscount(new BigDecimal(5.0));
order.setOrderTotal (new BigDecimal(25.0));
order.setTaxRate(new BigDecimal(15.0));
order.setAllowDiscounts(true);
order.setExternalOrderSource("ExternalSource");
order.setExternalOrderID("123456-7");

order.setAddresses(new CustomerAddress[] {address});
order.setOrderItems(new OrderItem[] {orderitem});
order.setAttributes(new NameValuePair[] {attribute});


// Import the order.
IntegerArrayApiResponse response = orderAPI.importOrder(securityToken, order);

// Examine the response for the new order ID.
if (!response.isSuccess()) {
	System.out.println("Failed to import order.");
} else {
	int importedOrderID = response.getData()[0];
	System.out.println("Imported order ID: " + importedOrderID);
}

Add a payment transaction to an order.

// Instantiate the web service proxy
OrdersAPISoapClient orderAPI = new OrdersAPISoapClient();

// User and password to authenticate with.
String username = "Testing";
String password = "Sup94zex";

// Authenticate and retrieve authentication token.
ApiResponse authResponse = orderAPI.authenticate(username, password);
String securityToken = authResponse.getMessage();

// Create the transaction.
Transaction transaction = new Transaction();
transaction.setTransactionAmount(new BigDecimal(60.00)); 
transaction.setTransactionType(1); 
transaction.setCardNumber("4111111111111111"); 
transaction.setCardName("Testing"); 
transaction.setCardExpiryMonth("11"); 
transaction.setCardExpiryYear("2018");

int orderID = 10001;

// Add the transaction to the order.
ApiResponse response = 
	orderAPI.addTransaction(securityToken, orderID, transaction);

// Examine the ApiResponse.
if (!response.isSuccess()) {
	System.out.println("Failed to add transaction.");
} else {
	System.out.println("Transaction added to order " + orderID);
}

Search for an order by email address.

// Instantiate the web service proxy
OrdersAPISoapClient orderAPI = new OrdersAPISoapClient();

// User and password to authenticate with.
String username = "Testing";
String password = "Sup94zex";

// Authenticate and retrieve authentication token.
ApiResponse authResponse = orderAPI.authenticate(username, password);
String securityToken = authResponse.getMessage();

String emailSearchTerm = "example.com";

// Search for all orders with a partial match on our email search term.
IntegerArrayApiResponse response = orderAPI.searchOrders(
	securityToken, emailSearchTerm, null, null, null, null, null, null);

// Examine the ApiResponse.
if (!response.isSuccess() || response.getData() == null) {
	System.out.println("Failed to perform search.");
} else {
	System.out.println("Found %s results.", response.getData().length);
	for(int orderID : response.getData()) {
		System.out.println(orderID);
	}
}

Void an order

// Instantiate the web service proxy
OrdersAPISoapClient orderAPI = new OrdersAPISoapClient();

// User and password to authenticate with.
String username = "Testing";
String password = "Sup94zex";

// Authenticate and retrieve authentication token.
ApiResponse authResponse = orderAPI.authenticate(username, password);
String securityToken = authResponse.getMessage();

Order order = orderAPI.create(securityToken);
// Void the order.
ApiResponse response = 
	orderAPI.voidOrder(securityToken, order.getID());

// Examine the ApiResponse.
if (!response.getSuccess()) {
	System.out.println("Failed to void the order.");
} else {
	System.out.println("Order voided");
}

Split an order

// Instantiate the web service proxy
OrdersAPISoapClient orderAPI = new OrdersAPISoapClient();

// User and password to authenticate with.
String username = "Testing";
String password = "Sup94zex";

// Authenticate and retrieve authentication token.
ApiResponse authResponse = orderAPI.authenticate(username, password);
String securityToken = authResponse.getMessage();

String barcode = "za783";
Order order = orderAPI.create(securityToken);
OrderItem item = new OrderItem();
item.setID(order.getID());
item.setBarcode(barcode);
item.setQuantity(5);

api.updateOrderItems(securityToken, item);

int orderItemID =
	api.retrieve(securityToken, order.ID).getOrderItems()[0].getID();

// Set up the orderitems and quantity.
Map<Integer,Integer> map = new HashMap<Integer,Integer>();
map.put(orderItemID, 2);

// Split the order.
OrderApiResponse response =
	api.splitOrder(securityToken, order.getID(), map);

// Examine the the OrderApiResponse for our order.
if (!response.getSuccess()) {
	System.out.println("Failed to split the given order.");
} else {
	// Extract the order from the response.
	Order splitOrder = response.getData()[0];
}