Cart

Requirements

These actions require the following app versions:

  • Point of Sale iOS v5.11.0 or above
  • Point of Sale Android v3.3.2 or above

Setup

Create an app and import the Cart module from @shopify/app-bridge/actions. Note that we'll be referring to this sample application throughout the examples below.

import createApp from '@shopify/app-bridge';
import { Cart } from '@shopify/app-bridge/actions';

const app = createApp({
  apiKey: '12345',
  shopOrigin: shopOrigin,
});

Create a cart

Create a cart and subscribe to cart updates:

var cart = Cart.create(app);
cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] cart update', payload);
});

Handling error

app.error(function (data: Error.ErrorAction) {
  console.info('[client] Error received: ', data);
});

Feature Detection

Cart actions are available only on the Shopify Point of Sale app, so it’s a good idea to check if an action is available before you call it. This makes sure that you're able to display the appropriate UI when a feature is or is not available. To learn more about Feature Detection, see Features.

The following example shows how you could use Feature Detection with cart actions by requesting if Cart.Action.FETCH is available and using the result to alter your UI.

Start off by requesting if the cart group is available:

app.featuresAvailable([Group.Cart]).then(function (state) {...});

The promise block resolves to a state object containing the status of the cart actions. Query for Cart.Action.FETCH and then Dispatch inside that object. If it's true, follow the instructions below for Fetch cart. If it's false, the cart action is not available in this context. Using this approach, it’s possible to distinguish between an empty cart and a context where cart is not available.

app.featuresAvailable(Group.Cart).then(function (state) {
  var _ref = state.Cart && state.Cart[Cart.Action.FETCH],
      Dispatch = _ref.Dispatch;

  if (Dispatch) {
    cart.dispatch(Cart.Action.FETCH);
  } else {
    var toastOptions = {
      message: 'Cart is not available',
      duration: 5000,
      isError: true
    };
    var toastError = Toast.create(app, toastOptions);
    toastError.dispatch(Toast.Action.SHOW);
  }
});

Update cart

GroupCart
ActionUPDATE
Action TypeAPP::CART::UPDATE
DescriptionRetrieves the latest state of the currently active cart from Shopify POS.

Subscribing to this action provides you with cart updates.

var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] fetchCart', payload);
  unsubscriber();
});
// ...
// Call other Cart actions

NoteAttribute Payload

Key Type Description
name String The name of the attribute.
value String The value of the attribute.

Response

Key Type Description
subtotal String The total cost of the current cart including discounts, but before taxes and shipping. Value is based on the shop's existing currency settings.
taxTotal String The sum of taxes for the current cart. Value is based on the shop's existing currency settings.
grandTotal String The total cost of the current cart, after taxes and discounts have been applied. Value is based on the shop's existing currency settings.
customer Customer? The customer associated to the current cart.
lineItems Array[LineItem] A list of lineItem objects.
noteAttributes Array[NoteAttribute]? A list of objects containing cart properties.
cartDiscount Discount? The current discount applied to the entire cart.
note String? A note associated with the cart.

Fetch cart

GroupCart
ActionFETCH
Action TypeAPP::CART::FETCH
DescriptionRequests the currently active cart from Shopify POS.

A cart needs to call fetch before receiving data in Cart.Action.UPDATE:

var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] fetchCart', payload);
  unsubscriber();
});
cart.dispatch(Cart.Action.FETCH);

Set customer

GroupCart
ActionSET_CUSTOMER
Action TypeAPP::CART::SET_CUSTOMER
DescriptionSets a customer on the current cart.

This is the customer that will be attached to the cart and subsequent order. You can either set a customer with an existing customer ID or create a new customer.

Existing customer with ID:

var customerPayload = {
    id: 123
};

New customer:

var customerPayload = {
    email: 'voisin@gmail.com',
    firstName: 'Sandrine',
    lastName: 'Voisin',
    note: 'First customer of 2019',
};
var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] setCustomer', payload);
  unsubscriber();
});
cart.dispatch(Cart.Action.SET_CUSTOMER, {
  data: cutomerPayload
});

Request

Key Type Description
data Customer The customer data.

Customer Payload

Key Type Description
id Number? The ID of existing customer.
email String? The email for new customer.
firstName String? The first name for new customer.
lastName String? The last name for new customer.
note String? The note for new customer.

Add customer address

GroupCart
ActionADD_CUSTOMER_ADDRESS
Action TypeAPP::CART::ADD_CUSTOMER_ADDRESS
DescriptionAdds a new address on the customer associated with the current cart. 
var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] addCustomerAddress', payload);
  unsubscriber();
});
cart.dispatch(Cart.Action.ADD_CUSTOMER_ADDRESS, {
  data: {
    address1: '528 Old Weston Road',
    address2: 'Apartment 201',
    city: 'Toronto',
    company: 'Eliteweb Inc.',
    country: 'Canada',
    countryCode: 'CA',
    firstName: 'Sandrine',
    lastName: 'Voisin',
    name: 'Sandrine Voisin',
    phone: '416 684 1787',
    province: 'Ontario',
    provinceCode: 'ON',
    zip: 'M6N 3B1',
  }
});

Request

Key Type Description
data Address The data for creating a new address.

Address Payload

Key Type Description
address1 String? The customer's primary address.
address2 String? Any extra information associated with the address (Apartment #, Suite #, Unit #, etc.).
city String? The name of the customer's city.
company String? The company name associated with address.
firstName String? The first name of the customer.
lastName String? The last name of the customer.
phone String? The phone number of the customer.
province String? The province or state of the address.
country String? The country of the address.
zip String? The ZIP or postal code of the address.
name String? The name of the address.
provinceCode String? The acronym of the province or state.
countryCode String? The Country Code in ISO 3166-1 (alpha-2) format.

Update customer address

GroupCart
ActionUPDATE_CUSTOMER_ADDRESS
Action TypeAPP::CART::UPDATE_CUSTOMER_ADDRESS
DescriptionUpdates a new address on the customer associated with the current cart. 
var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] updateCustomerAddress', payload);
  unsubscriber();
});
cart.dispatch(Cart.Action.UPDATE_CUSTOMER_ADDRESS, {
  index: 0,
  data: {
    address1: '528 Old Weston Road',
    address2: 'Apartment 201',
    city: 'Toronto',
    company: 'Eliteweb Inc.',
    country: 'Canada',
    countryCode: 'CA',
    firstName: 'Sandrine',
    lastName: 'Voisin',
    name: 'Sandrine Voisin',
    phone: '416 684 1787',
    province: 'Ontario',
    provinceCode: 'ON',
    zip: 'M6N 3B1',
  }
});

Request

Key Type Description
index Number The index of the address to update.
data Address The fields of the address to update.

Remove customer

GroupCart
ActionREMOVE_CUSTOMER
Action TypeAPP::CART::REMOVE_CUSTOMER
DescriptionRemoves a customer from the current cart. 
var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] removeCustomer', payload);
  unsubscriber();
});
cart.dispatch(Cart.Action.REMOVE_CUSTOMER);

Set discount

GroupCart
ActionSET_DISCOUNT
Action TypeAPP::CART::SET_DISCOUNT
DescriptionSets a discount on the current cart.

You can apply a discount to the entire cart, which will affect all line items. There are several different types of discounts. See below for an example of each type.

Flat amount discount:

var discountPayload = {
  amount: 1,
  discountDescription: "$1 off discount",
  type: 'flat',
}

Percentage discount:

var discountPayload = {
  amount: 0.5,
  discountDescription: "50% off discount",
  type: 'percent',
}

Discount code discount:

var discountPayload = {
  discountDescription: "Holiday Sale",
  discountCode: 'HOLIDAYSALE50',
}
var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] setDiscount', payload);
  unsubscriber();
});
cart.dispatch(Cart.Action.SET_DISCOUNT, {
  data: discountPayload
});

Discount Amount Payload

Key Type Description
amount Number The discount amount to be applied to the subtotal of the cart as a flat value or total percentage discount. flat discount amounts must be greater than 0. Discounts greater than the subtotal of the cart will be reduced to the subtotal amount. percent discount amounts must be between 0.0 and 1.0.
discountDescription String? A description of the discount being applied. Defaults to Discount, if not supplied.
type String? The discount type. The options are flat or percent. Defaults to flat, if not supplied.

Discount Code Payload

Key Type Description
discountCode String The discount code to apply to the current cart.

Request

Key Type Description
data DiscountAmount | DiscountCode The type of discount to apply to the current cart.

Remove discount

GroupCart
ActionREMOVE_DISCOUNT
Action TypeAPP::CART::REMOVE_DISCOUNT
DescriptionRemoves a discount from the current cart. 
var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] removeDiscount', payload);
  unsubscriber();
});
cart.dispatch(Cart.Action.REMOVE_DISCOUNT);

Set cart properties

GroupCart
ActionSET_PROPERTIES
Action TypeAPP::CART::SET_PROPERTIES
DescriptionAdds additional properties to the current cart. 
var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] setProperties', payload);
  unsubscriber();
});
cart.dispatch(Cart.Action.SET_PROPERTIES, {
  data: {
    referral: 'Shopify',
    userID: '1234',
  }
});

Request

Key Type Description
data Object The key-value pairs of properties to add to the current cart.

Remove cart properties

GroupCart
ActionREMOVE_PROPERTIES
Action TypeAPP::CART::REMOVE_PROPERTIES
DescriptionRemoves one or more properties from the current cart. 
var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] removeProperties', payload);
  unsubscriber();
});
cart.dispatch(Cart.Action.REMOVE_PROPERTIES, {
  data: ['referral', 'userID']
});

Request

Key Type Description
data Array[String] A list of properties to remove from the current cart.

Add line item

GroupCart
ActionADD_LINE_ITEM
Action TypeAPP::CART::ADD_LINE_ITEM
DescriptionAdds a new line item to the current cart.

Line items can be added to the cart in two different ways: as a variant of a product, or as a quick sale item (usually used for one-off sales on items not backed by a variant).

Quick Sale line item:

var lineItemPayload = {
  price: 20,
  quantity: 1,
  title: 'Bab Low - Blue Jay // White Soles',
};

Variant line item:

var lineItemPayload = {
  variantId: 1234,
  quantity: 1
};
var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] addLineItem', payload);
  unsubscriber();
});
cart.dispatch(Cart.Action.ADD_LINE_ITEM, {
  data: lineItemPayload
});

Line item Payload

Key Type Description
price Number? The price of the line item. Required if a variantId is not provided. Must be greater than or equal to 0.
quantity Number The amount of items to add. Defaults to 1 if not provided. Must be greater than 0.
title String? The name of the product, defaults to "Quick sale" if not supplied.
variantId Number? The unique ID of the variant being added. If not included, the product will be considered a custom sale.
discount DiscountAmount? A discount to apply to the line item.

Request

Key Type Description
data LineItem The data for creating a new line item in the current cart.

Update line item

GroupCart
ActionUPDATE_LINE_ITEM
Action TypeAPP::CART::UPDATE_LINE_ITEM
DescriptionUpdates an existing line item quantity in the cart. 
var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] updateLineItem', payload);
  unsubscriber();
});
cart.dispatch(Cart.Action.UPDATE_LINE_ITEM, {
  index: 0,
  data: {
    quantity: 100,
  }
});

Line item update payload

Key Type Description
quantity Number The amount of items to add. Must be greater than 0.

Request

Key Type Description
index Number Index of line item to update
data Line Item Update The data for updating a line item at the specified index.

Remove line item

GroupCart
ActionREMOVE_LINE_ITEM
Action TypeAPP::CART::REMOVE_LINE_ITEM
DescriptionRemoves an existing line item from the cart. 
var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] removeLineItem', payload);
  unsubscriber();
});
cart.dispatch(Cart.Action.REMOVE_LINE_ITEM, {
  index: 0
});

Request

Key Type Description
index Number The index of line item to remove.

Set line item discount

GroupCart
ActionSET_LINE_ITEM_DISCOUNT
Action TypeAPP::CART::SET_LINE_ITEM_DISCOUNT
DescriptionSets the discount on a line item in the current cart.

Unlike cart discounts, line item discounts can't use discount codes. They support only flat amount discounts and percentage discounts.

Flat amount discount:

var discountPayload = {
  amount: 1,
  discountDescription: "$1 off discount",
  type: 'flat',
}

Percentage discount:

var discountPayload = {
  amount: 0.5,
  discountDescription: "50% off discount",
  type: 'percent',
}
var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] setLineItemDiscount', payload);
  unsubscriber();
});
cart.dispatch(Cart.Action.SET_LINE_ITEM_DISCOUNT, {
  index: 0,
  data: discountPayload
});

Request

Key Type Description
index Number The index of the line item to apply the discount to.
data DiscountAmount The discount to apply to the line item.

Remove line item discount

GroupCart
ActionREMOVE_LINE_ITEM_DISCOUNT
Action TypeAPP::CART::REMOVE_LINE_ITEM_DISCOUNT
DescriptionRemoves a line item discount in the current cart. 
var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] removeLineItemDiscount', payload);
  unsubscriber();
});
cart.dispatch(Cart.Action.REMOVE_LINE_ITEM_DISCOUNT, {
  index: 0
});

Request

Key Type Description
index Number The index of the line item to remove the discount from.

Set line item properties

GroupCart
ActionSET_LINE_ITEM_PROPERTIES
Action TypeAPP::CART::SET_LINE_ITEM_PROPERTIES
DescriptionAdds a property to a given line item in the current cart. 
var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] setLineItemProperties', payload);
  unsubscriber();
});
cart.dispatch(Cart.Action.SET_LINE_ITEM_PROPERTIES, {
  index: 0,
  data: {
    referral: 'Shopify',
    userID: '1234',
  }
});

Request

Key Type Description
data Object The key-value pairs of properties to add to the specified line item.

Remove line item properties

GroupCart
ActionREMOVE_LINE_ITEM_PROPERTIES
Action TypeAPP::CART::REMOVE_LINE_ITEM_PROPERTIES
DescriptionRemoves a property from a given line item in the current cart.

When removing properties, reference the key of property. In the properties that were set on the cart above, the keys were: referral and userID. You can pass in either of those values to remove them.

var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] removeLineItemProperties', payload);
  unsubscriber();
});
cart.dispatch(Cart.Action.REMOVE_LINE_ITEM_PROPERTIES, {
  index: 0,
  data: ['referral', 'userID']
});

Request

Key Type Description
index Number The index of the line item to remove properties from.
data Array[String] A list of properties to remove from the specified line item.

Clear cart

GroupCart
ActionCLEAR
Action TypeAPP::CART::CLEAR
DescriptionRemove all line items from the current cart. 
var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {
  console.log('[Client] clear', payload);
  unsubscriber();
});
cart.dispatch(Cart.Action.CLEAR);