A product is an individual item for sale in a merchant's store. Products can be physical goods, servics or digital downloads.

When working with products it is important to undertand what a product variant is. A variant is an individual style or type of a product. For example, a t-shirt may be available with different choices for size and colour. Each valid combination of optoins for these two attributes will be a variant of the t-shirt product (i.e. Large White t-shirt, Small Red t-shirt).
If a product only has one style or type, then it is considered to be a single variant.

This page covers:

Retrieving a Product

Retrieve the product from the ProductWorkflow. (see triggers and workflows for how to get the workflow).

The workflow also contains a possible set of coupons that the user can redeem on this or future purchases. The coupons are automatically saved to the user's profile but returned here so they can be displayed to the user.

Product product = workflow.getProduct();
List<Coupon> coupons = workflow.getTriggeredCoupons();
// Display coupons to user

Checking if a Product has Multiple Variants

If a product has multiple variants it will have options that the user must choose from in order to identify which variant they want. A single variant product will not have any option choices.

Check to see whether the product has option choices:

if (product.hasOptionChoices()) {
	// Get the user to select a product variant
} else {
	// The product only has a single variant
	ProductVariant selectedVariant = product.getVariants().get(0);

Selecting a Product Variant

The product options must be displayed to the user so they can choose a single product variant, but not all options are valid in combination with one another. For example, the merchant might not sell a 'Large Pink t-shirt' but they do sell a 'Small Pink t-Shirt'

To simply this process, a ProductVariantPicker is provided that you can bind to your UI to help users choose one option at a time until a valid combination of options has been chosen, resulting in a single variant.
For each choice (e.g. size or color) there are a number of options (e.g. Red and Blue options for color) and each option has a state indicating whether it is currently chosen and whether it can be chosen based on the currently chosen options.

  1. If the product has multiple variants, create a ProductVariantPicker and get the option choices for the product:

Use the ProductVariantPicker to get a list of ProductOptionChoice, one for each available choice (e.g. Size, Color). Each ProductOptionChoice contains a list of ProductOptionState objects which is a wrapper for the ProductOption to provide state information like whether it is currently chosen or available for selection.

ProductVariantPicker picker = new ProductVariantPicker(product);
List<ProductOptionChoice> productOptionChoices = picker.getOptionChoices();
// Display the choices in some manner

  1. To choose a specific option call the pickers chooseOption method:

This will update the state of the options in the choices list based on the currently chosen options. The list is updated in-place so there is no need to get the list from the picker again.

// Update picker with option selected by the user

  1. Use the getChosenOptions method to find out what the currently chosen options are:

Like the list of option choices, when changes are made this list is updated in-place:

List<ProductOption> chosenOptions = picker.getChosenOptions();

  1. You can find out which variants match the current option choices:
List<ProductVariant> variants = picker.getVariants();

Once a desired option has been selected for each choice, the number of variants returned will either be 1 (the desired variant) or 0 (no variants available that match the current selection).

  1. To deselect an already chosen option:

To un-choose an option:


To clear all chosen options:


Checking if User Has Picked a Variant

To determine if a variant has been selected, you need to check if the user has selected an option for every choice.
The isOptionChosenForEveryChoice method returns 'true' once a single variant has been chosen:


Saving and Restoring the Picker State

  1. To save the picker state when your Activity is destroyed, use the saveInstanceState picker method:
public void onSaveInstanceState(Bundle outState) {
	outState.putParcelable("picker", picker.saveInstanceState());
  1. You can restore the picker state using the restoreInstanceState method:
public void onCreate(Bundle savedInstanceState) {
	picker = new ProductVariantPicker(product);
public void onRestoreInstanceState(Bundle savedInstanceState) {
  1. Or when instantiating your picker if you know the saved state is not null:
public void onCreate(Bundle savedInstanceState) {
	if (savedInstanceState != null) {
		picker = new ProductVariantPicker(product, savedInstanceState.getParcelable("picker"));
	} else {
		picker = new ProductVariantPicker(product);

Useful Product Methods

  1. The following methods can be used to obtian useful product information:
// Get the ID of the product.
String productId = product.getProductId();

// Get the ID of the merchant which this product is from.
String merchantId = product.getMerchantId();

// Get The Global Trade Item Number (GTIN) that uniquely identifies the product globally, if it has one.
String gtin = product.getGtin();

// Get the product title
String title = product.getTitle();

// Get the product description.
String productDescription = product.getDescription();

// Get the brand associated with the product.
String brand = product.getBrand();

// Get the product condition. e.g. new, refurbished, used or unknown
ProductCondition condition = product.getCondition();

// Get a URL to view more information about the product. The URL is optional
URI productLink = product.getLink();

// Get the list of categories this product is in.
List<String> categories = product.getCategories();

Next Step: Adding a Product Variant to a Basket

Add the product variant to the users basket in preparation for check out.


To explore this topic in detail, import the sample app and review the ProductDetailsActivity class.