> Note: > This is a legacy API. Use the latest version of [`POS`](/docs/api/app-bridge-library/apis/pos) instead. ## 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 > 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](/docs/api/app-bridge/previous-versions/actions/features). ## 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. > Note > In the following example, `config` is a valid App Bridge configuration object. Learn more about [configuring App Bridge](/docs/api/app-bridge/previous-versions/app-bridge-from-npm/app-setup#initialize-shopify-app-bridge-in-your-app). ```js import createApp from '@shopify/app-bridge'; import { Cart } from '@shopify/app-bridge/actions'; const app = createApp(config); ``` ## Create a cart Create a cart and subscribe to cart updates: ```js var cart = Cart.create(app); cart.subscribe(Cart.Action.UPDATE, function (payload) { console.log('[Client] cart update', payload); }); ``` ## Handling error ```js 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](/docs/api/app-bridge/previous-versions/actions/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: ```js 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](#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. ```js 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. ```js 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`: ```js 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: ```js var customerPayload = { id: 123 }; ``` New customer: ```js var customerPayload = { email: 'voisin@gmail.com', firstName: 'Sandrine', lastName: 'Voisin', note: 'First customer of 2019', }; ``` ```js var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) { console.log('[Client] setCustomer', payload); unsubscriber(); }); cart.dispatch(Cart.Action.SET_CUSTOMER, { data: customerPayload }); ``` ### 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.
> Note: A customer must exist on the cart for this action to be successful. ```js 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.
> 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. ```js 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.
```js 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: ```js var discountPayload = { amount: 1, discountDescription: "$1 off discount", type: 'flat', } ``` Percentage discount: > Note: The `amount` is a float value where 1.0 is a 100% discount and 0.0 is a 0% discount. ```js var discountPayload = { amount: 0.5, discountDescription: "50% off discount", type: 'percent', } ``` Discount code discount: ```js var discountPayload = { discountCode: 'HOLIDAYSALE50', } ``` ```js 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.
```js 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.
> Note: Each key/value pair in the payload is a single property. ```js 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.
> 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. ```js 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: ```js var lineItemPayload = { price: 20, quantity: 1, title: 'Bab Low - Blue Jay // White Soles', taxable: true }; ``` Variant line item: ```js var lineItemPayload = { variantId: 1234, quantity: 1 }; ``` ```js 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.
properties Array[NoteAttribute]? A list of objects containing item properties.
### 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.
> 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. ```js 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.
> 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. ```js 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. > 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: ```js var discountPayload = { amount: 1, discountDescription: "$1 off discount", type: 'flat', } ``` Percentage discount: > Note: The `amount` is a float value where 1.0 is a 100% discount and 0.0 is a 0% discount. ```js var discountPayload = { amount: 0.5, discountDescription: "50% off discount", type: 'percent', } ``` ```js 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.
> 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. ```js 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.
> 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. ```js 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: Each key/value pair in the payload is a single property. ### 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.
> 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. ```js 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.
```js var unsubscriber = cart.subscribe(Cart.Action.UPDATE, function (payload) { console.log('[Client] clear', payload); unsubscriber(); }); cart.dispatch(Cart.Action.CLEAR); ```