Orders API Examples - C#

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 C#.

These examples assume the use of a generated XML web service client. To generate such a client, a tool such as WSDL.exe can be used. A detailed description on this tool can be found on MSDN - 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.Message;

// 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.Success || response.Data.Count() == 0) {
	Console.WriteLine("Failed to retrieve order: {0}", orderID);
} else {
	// Extract the order from the response.
	Order order = response.Data[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.Message;

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

// Examine the OrderApiResponse for our order.
if (!retrieveResponse.Success || retrieveResponse.Data.Count() == 0) {
	Console.WriteLine("Failed to create new order.");
} else {
	// Extract the new order from the response.
	Order order = retrieveResponse.Data[0];
	Console.WriteLine("New order ID: " + order.ID);
}

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.Message;

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.Success) {
	Console.WriteLine("Added new order item.");
} else {
	Console.WriteLine("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.Message;

// A new order to import.
Order order = new Order() {
	Phone = "1234567",
	Email = "[email protected]",
	Status = OrderStatus.Initiated,
	AdminReference = "Reference",
	CustomerReference = "Customer Reference",
	Currency = "NZD",
	PaymentMethod = 1,
	Freight = 10.0m,
	FreightDiscount = 0,
	OrderBasedDiscount = 5.0m,
	OrderTotal = 25.0m,
	TaxRate = 15.0m,

	Website = 1,
	FraudProfileXML = string.Empty,
	AllowDiscounts = true,
	ExternalOrderSource = "ExternalSource",
	ExternalOrderID = "123456-7",

	Addresses =  new CustomerAddress[] { new CustomerAddress {
		Type = "Shipping",
		FirstName = "FirstName",
		LastName = "LastName",
		Street = "Street",
		Suburb = "Suburb",
		City = "City",
		Company = "Company",
		State = "State",
		Country = "NZL",
		Postcode = "1111",
		ExtraInformation = "ExtraInfomation"
		}
	},

	OrderItems = new OrderItem[] { new OrderItem {
		ProductItem = 201,
		Quantity = 1,
		StatusCode = OrderItemStatus.Unordered,
		UnitPrice = 20.00m,
		Personalisation = new ItemPersonalisation() {
			Price = 10.50m,
			AdditionalData = "<info>Example Custom data</info>",
			Components = new PersonalisedComponent[] { 
				new PersonalisedComponent() {
					Type = "Name",
					Value = "John Doe",
					Composition = new NameValuePair[] {
			new NameValuePair {Name = "Colour", Value = "Red"}
					}
				}
			}
		}
	},

	Attributes = new NameValuePair[] { new NameValuePair {
		Name = "Attribute Name",
		Value = "Attribute Value"
		}
	}
};

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

// Examine the response for the new order ID.
if (!response.Success) {
	Console.WriteLine("Failed to import order.");
} else {
	int importedOrderID = response.Data[0];
	Console.WriteLine("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.Message;

// Create the transaction.
Transaction transaction = new Transaction { 
	TransactionAmount = 60m, 
	TransactionType = 1, 
	CardNumber = "4111111111111111", 
	CardName = "Testing", 
	CardExpiryMonth = "11", 
	CardExpiryYear = "2018" };

int orderID = 10001;

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

// Examine the ApiResponse.
if (!response.Success) {
	Console.WriteLine("Failed to add transaction.");
} else {
	Console.WriteLine("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.Message;

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.Success || response.Data == null) {
	Console.WriteLine("Failed to perform search.");
} else {
	Console.WriteLine("Found {0} results.", response.Data.Count);
	foreach (int orderID in response.Data) {
		Console.WriteLine(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.Message;

Order order = orderAPI.Create(securityToken);
// Void the order.
ApiResponse response = 
	orderAPI.VoidOrder(securityToken, order.ID);

// Examine the ApiResponse.
if (!response.Success) {
	Console.WriteLine("Failed to void the order.");
} else {
	Console.WriteLine("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.Message;

String barcode = "za783";
Order order = orderAPI.Create(securityToken);
api.UpdateOrderItems(securityToken, new OrderItem() { 
	OrderID = order.ID
	, Barcode = barcode
	, Quantity = 5 });

int orderItemID =
	api.Retrieve(securityToken, order.ID).OrderItems.First().ID;

// Set up the orderitems and quantity.
var pair = new IdentifierValuePair<int, int>[] { 
	new IdentifierValuePair<int, int>(orderItemID, 2)
};

// Split the order.
OrderApiResponse response =
	api.SplitOrder(securityToken, order.ID, pair);

// Examine the OrderApiResponse for our order.
if (!response.Success || response.Data.Count() == 0) {
	Console.WriteLine("Failed to split the given order.");
} else {
	// Extract the order from the response.
	Order splitOrder = response.Data[0];
}