Cart

Note

This is a legacy API. Use the latest version of POS instead.

Anchor to RequirementsRequirements

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

Note

Cart features are only available when opening an embedded app through a link on Point of Sale while editing the cart. To learn more about how to check for cart features, see Features.

Anchor to SetupSetup

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.

Note

In the following example, config is a valid App Bridge configuration object. Learn more about configuring App Bridge.

import createApp from '@shopify/app-bridge';

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

const app = createApp(config);

Anchor to Create a cartCreate 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);

});

Anchor to Handling errorHandling error

app.error(function (data: Error.ErrorAction) {

console.info('[client] Error received: ', data);

});

Anchor to Feature DetectionFeature 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);

}

});

Anchor to Update cartUpdate 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

Anchor to NoteAttribute PayloadNoteAttribute Payload

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

Anchor to ResponseResponse

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.

Anchor to Fetch cartFetch 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);

Anchor to Set customerSet 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: customerPayload

});

Anchor to RequestRequest

Key	Type	Description
`data`	Customer	The customer data.

Anchor to Customer PayloadCustomer 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.

Anchor to Add customer addressAdd 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.

Note

Note: A customer must exist on the cart for this action to be successful.

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',

}

});

Anchor to RequestRequest

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

Anchor to Address PayloadAddress 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.

Anchor to Update customer addressUpdate 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.

Note

Note: The first parameter is the index of the customer address you're updating. If there is no address at that index, this action will not be successful.

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',

}

});

Anchor to RequestRequest

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

Anchor to Remove customerRemove 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);

Anchor to Set discountSet 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:

Note

Note: The amount is a float value where 1.0 is a 100% discount and 0.0 is a 0% discount.

var discountPayload = {

amount: 0.5,

discountDescription: "50% off discount",

type: 'percent',

}

Discount code discount:

var discountPayload = {

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

});

Anchor to Discount Amount PayloadDiscount 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.

Anchor to Discount Code PayloadDiscount Code Payload

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

Anchor to RequestRequest

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

Anchor to Remove discountRemove 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);

Anchor to Set cart propertiesSet cart properties

Group	Cart
Action	SET_PROPERTIES
Action Type	APP::CART::SET_PROPERTIES
Description	Adds additional properties to the current cart.

Note

Note: Each key/value pair in the payload is a single property.

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',

}

});

Anchor to RequestRequest

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

Anchor to Remove cart propertiesRemove cart properties

Group	Cart
Action	REMOVE_PROPERTIES
Action Type	APP::CART::REMOVE_PROPERTIES
Description	Removes one or more properties from the current cart.

Note

Note: When removing properties, reference the key of the property. In the example above, two properties were set on the cart, with keys referral and userID. Pass in either of those values to remove them.

var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {

console.log('[Client] removeProperties', payload);

unsubscriber();

});

cart.dispatch(Cart.Action.REMOVE_PROPERTIES, {

data: ['referral', 'userID']

});

Anchor to RequestRequest

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

Anchor to Add line itemAdd 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

});

Anchor to Line item PayloadLine 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.
`properties`	Array[NoteAttribute]?	A list of objects containing item properties.

Anchor to RequestRequest

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

Anchor to Update line itemUpdate 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.

Note

Note: The first parameter is the index of the line item to update. If there is no line item at that index, this action will not be successful. Only the quantity property can be updated.

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,

}

});

Anchor to Line item update payloadLine item update payload

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

Anchor to RequestRequest

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.

Anchor to Remove line itemRemove line item

Group	Cart
Action	REMOVE_LINE_ITEM
Action Type	APP::CART::REMOVE_LINE_ITEM
Description	Removes an existing line item from the cart.

Note

Note: The first parameter is the index of the line item to remove. If there is no line item at that index, this action will not be successful.

var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) {

console.log('[Client] removeLineItem', payload);

unsubscriber();

});

cart.dispatch(Cart.Action.REMOVE_LINE_ITEM, {

index: 0

});

Anchor to RequestRequest

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

Anchor to Set line item discountSet 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.

Note

Note: The first parameter is the index of the line item to applying the discount to. If there is no line item at that index, this action will not be successful.

Flat amount discount:

var discountPayload = {

amount: 1,

discountDescription: "$1 off discount",

type: 'flat',

}

Percentage discount:

Note

Note: The amount is a float value where 1.0 is a 100% discount and 0.0 is a 0% 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

});

Anchor to RequestRequest

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.

Anchor to Remove line item discountRemove 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.

Note

Note: The first parameter is the index of which line item we're removing a discount from. If there is no line item at that index then this action will not be successful.

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

});

Anchor to RequestRequest

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

Anchor to Set line item propertiesSet 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.

Note

Note: The first parameter is the index of which line item we're setting properties on. If there is no line item at that index then this action will not be successful.

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',

}

});

Note

Note: Each key/value pair in the payload is a single property.

Anchor to RequestRequest

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

Anchor to Remove line item propertiesRemove 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.

Note

Note: The first parameter is the index of which line item we're removing properties from. If there is no line item at that index then this action will not be successful.

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']

});

Anchor to RequestRequest

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.

Anchor to Clear cartClear 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);

Was this page helpful?