Use the Order Connector

United States
Canada
Europe
Latin America

To see our APIs in action, visit the Clover Android SDK examples directory in the Clover Android SDK. The examples use the Clover APIs to connect to Services, query Clover ContentProviders, and fetch data directly from the Clover REST API. This tutorial provides basic steps for using the OrderConnector.

Prerequisites

Your app needs the following Clover app permissions to complete this tutorial:

  • Read orders
  • Write orders
  • Read inventory

Build an order

You can use the OrderConnector to create Orders, then associate them with relevant LineItems, Discounts, Modifiers, and other related objects.

  1. Get the merchant's CloverAccount.
private Account mAccount;
protected void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);
  mAccount = CloverAccount.getAccount(this);
}
  1. Use the OrderConnector and InventoryConnector to establish persistent connections.
if (mAccount != null) {
  orderConnector = new OrderConnector(this, mAccount, null);
  orderConnector.connect();
  inventoryConnector = new InventoryConnector(this, mAccount, null);
  inventoryConnector.connect();
}

📘

NOTE

Once your connections are in place, the work of interacting with merchant data (steps 4-8) should be completed on an asynchronous thread.

  1. Use the orderConnector to create a new Order.
mOrder = orderConnector.createOrder(new Order());

When using createOrder, you can only set information for specific {@link Order} fields:

  • groupLineItems
  • manualTransaction
  • note
  • orderType
  • state
  • taxRemoved
  • testMode
  • title

If you want to add a customer, line item, or other data not listed above, you must first create the order and then use theupdateOrder to modify the order with additional information.

  1. Use the inventoryConnector to get an Item, and then use the Item to add a LineItem to the Order. Note that there are separate methods for adding fixed-price, per-unit, and variable-price Items.
merchantItems = inventoryConnector.getItems();

mItem = merchantItems.get(itemId);

if (mItem.getPriceType() == PriceType.FIXED) {
    mLineItem = orderConnector.addFixedPriceLineItem(mOrder.getId(), mItem.getId(), null, null);
} else if (mItem.getPriceType() == PriceType.PER_UNIT) {
    mLineItem = orderConnector.addPerUnitLineItem(mOrder.getId(), mItem.getId(), 1, null, null);
} else { // The item must be of a VARIABLE PriceType
    mLineItem = orderConnector.addVariablePriceLineItem(mOrder.getId(), mItem.getId(), 5, null, null);
}
  1. Use the inventoryConnector.bulkAssignColorToItems() method in InventoryConnector.java to colorCode to an Item and to a Category. For more information, see Create an item for the inventory and Create a category.

  2. Create Discounts separately.

//Percentage discount
final com.clover.sdk.v3.order.Discount discount1 = new Discount();
discount1.setPercentage(10l);
discount1.setName("Example 10% Discount");

//Static discount
final Discount discount2 = new Discount();
discount2.setAmount(-100l);
discount2.setName("Example 1 base unit of currency Discount");
  1. Apply the Discount to an Order or individual lineItem.
//Apply first discount to whole order
orderConnector.addDiscount(mOrder.getId(), discount1);

//Apply second discount only to the first line item
orderConnector.addLineItemDiscount(mOrder.getId(), mLineItem.getId(), discount2);
  1. Use the InventoryConnector to retrieve ModifierGroups and their Modifiers, then apply Modifiers to the relevant lineItems.
List<ModifierGroup> modifierGroups = inventoryConnector.getModifierGroupsForItem(mItem.getId());

//Check if any modifier is available to the item
if (modifierGroups.size() > 0){
    List<Modifier> modifiers = modifierGroups.get(0).getModifiers();
    if (modifiers.size() > 0){
        //If so, apply the first modifier to the line item
        orderConnector.addLineItemModification(mOrder.getId(), mLineItem.getId(), modifiers.get(0));
    }
}
  1. After your asynchronous task finishes, disconnect from unneeded connectors.
if (orderConnector != null) {
    orderConnector.disconnect();
    orderConnector = null;
}
if (inventoryConnector != null) {
    inventoryConnector.disconnect();
    inventoryConnector = null;
}
  1. Optionally, you can get an order and print a payment receipt. Use the PrintJob.print() to print a sale receipt.

Here's one example of how to print a payment receipt.

new AsyncTask<Void, Void, Void>() {
  @Override
  protected Void doInBackground(Void... params) {
    try {
      PrintJob printJob = new StaticOrderPrintJob.Builder().order(mOrder).build();
      printJob.print(getApplicationContext(), account);
      return null;
    } catch (ClientException | ServiceException | BindingException | RemoteException e) {
      e.printStackTrace();
    }
    return null;
  }
}.execute();

If the merchant issues a refund, the StaticReceiptPrintJob links the refund to the main order and prints the sale UUID in the receipt.