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

Group	Cart
Action	UPDATE
Action Type	APP::CART::UPDATE
Description	Retrieves 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

Group	Cart
Action	FETCH
Action Type	APP::CART::FETCH
Description	Requests 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

Group	Cart
Action	SET_CUSTOMER
Action Type	APP::CART::SET_CUSTOMER
Description	Sets 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

Group	Cart
Action	ADD_CUSTOMER_ADDRESS
Action Type	APP::CART::ADD_CUSTOMER_ADDRESS
Description	Adds 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

Group	Cart
Action	UPDATE_CUSTOMER_ADDRESS
Action Type	APP::CART::UPDATE_CUSTOMER_ADDRESS
Description	Updates 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

Group	Cart
Action	REMOVE_CUSTOMER
Action Type	APP::CART::REMOVE_CUSTOMER
Description	Removes 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

Group	Cart
Action	SET_DISCOUNT
Action Type	APP::CART::SET_DISCOUNT
Description	Sets 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

Group	Cart
Action	REMOVE_DISCOUNT
Action Type	APP::CART::REMOVE_DISCOUNT
Description	Removes 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

Group	Cart
Action	SET_PROPERTIES
Action Type	APP::CART::SET_PROPERTIES
Description	Adds 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

Group	Cart
Action	REMOVE_PROPERTIES
Action Type	APP::CART::REMOVE_PROPERTIES
Description	Removes 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

Group	Cart
Action	ADD_LINE_ITEM
Action Type	APP::CART::ADD_LINE_ITEM
Description	Adds 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',
  taxable: true
};

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.
`taxable`	Boolean?	A flag that indicates if the line item changes the taxes of the cart. Defaults to `true` if not provided. Only available to be set on custom sale items.

Request

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

Update line item

Group	Cart
Action	UPDATE_LINE_ITEM
Action Type	APP::CART::UPDATE_LINE_ITEM
Description	Updates 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

Group	Cart
Action	REMOVE_LINE_ITEM
Action Type	APP::CART::REMOVE_LINE_ITEM
Description	Removes 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

Group	Cart
Action	SET_LINE_ITEM_DISCOUNT
Action Type	APP::CART::SET_LINE_ITEM_DISCOUNT
Description	Sets 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

Group	Cart
Action	REMOVE_LINE_ITEM_DISCOUNT
Action Type	APP::CART::REMOVE_LINE_ITEM_DISCOUNT
Description	Removes 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

Group	Cart
Action	SET_LINE_ITEM_PROPERTIES
Action Type	APP::CART::SET_LINE_ITEM_PROPERTIES
Description	Adds 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

Group	Cart
Action	REMOVE_LINE_ITEM_PROPERTIES
Action Type	APP::CART::REMOVE_LINE_ITEM_PROPERTIES
Description	Removes 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

Group	Cart
Action	CLEAR
Action Type	APP::CART::CLEAR
Description	Remove 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);

Cart

Requirements

Setup

Create a cart

Handling error

Feature Detection

Update cart

NoteAttribute Payload

Response

Fetch cart

Set customer

Request

Customer Payload

Add customer address

Request

Address Payload

Update customer address

Request

Remove customer

Set discount

Discount Amount Payload

Discount Code Payload

Request

Remove discount

Set cart properties

Request

Remove cart properties

Request

Add line item

Line item Payload

Request

Update line item

Line item update payload

Request

Remove line item

Request

Set line item discount

Request

Remove line item discount

Request

Set line item properties

Request

Remove line item properties

Request

Clear cart

On this page