Methods

Deprecated

POS App SDK is deprecated. Use Shopify App Bridge instead.

There are a number of methods that can be used on the ShopifyPOS integrations. The following table links to example code, and displays which integrations can access which methods. For the different types of errors that you can expect for these methods, refer to the Errors table.

Name	Description	Edit Cart	Order complete
POS Dialog	Standard browser dialog support.	✔	✔
POS Callbacks	Callbacks and error handling.	✔	✔
POS Initialize		✔	✔
POS Ready		✔	✔
POS Remote Redirect	Dispatches away from the app to a remote URL.	✔	✔
POS Flash Notice	Displays a successful or neutral message in Shopify POS.	✔	✔
POS Flash Error	Displays a message in Shopify POS styled as an error.	✔	✔
POS Fetch User	Get info on a Shopify POS user.	✔	✔
POS Fetch Location	Get the currently set location of Shopify POS.	✔	✔
POS Close Modal	Closes the currently open app, and returns the user to Shopify POS.	✔	✔
Cart Fetch	Retrieve the currently active cart from Shopify POS.	✔
Cart Set Customer	Sets a customer on the current cart.	✔
Cart Remove Customer	Removes a customer from the current cart.	✔
Cart Add Customer Address	Adds a new address on the customer associated with the current cart.	✔
Cart Update Customer Address	Updates a new address on the customer associated with the current cart.	✔
Cart Set Discount	Sets a discount on the current cart.	✔
Cart Remove Discount	Removes a discount from the current cart.	✔
Cart Add Properties	Adds arbitrary properties to the current cart.	✔
Cart Remove Properties	Remove one or more properties from the current cart.	✔
Cart Clear	Remove all line items from the cart.	✔
Add Line Item	Adds a new line item to the current cart.	✔
Update Line Item	Updates an existing line item quantity in the cart.	✔
Remove Line Item	Removes an existing line item from the cart.	✔
Set Line Item Discount	Sets the discount on a line item in the current cart.	✔
Remove Line Item Discount	Removes a line item discount in the current cart.	✔
Add Line Item Properties	Adds a property to a given line item in the current cart.	✔
Remove Line Item Properties	Removes a property from a given line item in the current cart.	✔

POS Dialog

You can use the following list of standard browser dialogs:

• alert()
• confirm()
• prompt().

They will be styled slightly differently depending on your version of iOS.

POS Callbacks

Note

The equivalent methods in Shopify App Bridge are subscribe, using the Cart action, and Error.

Many of the methods in the POS App SDK include support for callback methods that are automatically invoked when the requested action has succeeded or failed. They can be passed to a function in the following format:

Success callbacks receive a single argument, which is different depending on the method invoked. In all of the functions defined on Cart, the argument to success will be the latest state of the cart. Methods that do not pass a Cart back will explicitly state what they pass in the documentation below.

Error callbacks receive a single argument, errors, on invocation. This is an array of Error objects, each of which contains the following keys:

Key	Type	Description
property	String	Reference to an object property in the original payload which contained the error. If the error is not related to a specific property, property will be null. Example: "variant_id".
message	String	A description of the error that occurred. Example: "must not be blank".
errorType	String	The category of error that occurred. Valid values include: persistence, authorization, misconfiguration, validation, and unsupported_operation.

POS Initialize

Note

The equivalent method in Shopify App Bridge is createApp.

Should be called immediately after the script file has loaded, as early as possible on the page (not in a jQuery.ready() or similar). It will initialize data values, and setup our initializers.

The config hash can contain the following keys:

Key	Type	Description
apiKey	String	ff9b1d04414785029e066f8fd0465d00 or similar. The client credentials provided to you for your application in the Partner Dashboard.
shopOrigin	String	The origin of the Shopify shop. This will come out of the session values returned from the Shopify API and should be set dynamically for each different store. The origin must always include the protocol, and is constructed as "https://shopname.myshopify.com".
debug	boolean	Defaults to false. Will activate console.log logging output.

POS Ready

Note

There is no equivalent method in Shopify App Bridge. This functionality is no longer necessary. Shopify App Bridge actions can be dispatched immediately after the App Bridge client instance is created using createApp.

Works similarly to jQuery's ready() function. It can be called many times on a page, it accepts functions, and when the app is presented in POS, it will call the functions in order.

POS Remote Redirect

Note

The equivalent action in Shopify App Bridge is Redirect, specifically Redirect.Action.REMOTE.

Dispatches away from the app to a remote URL. The path must be an absolute URL prefixed with http or https. Context will shift from third party (within an iframe) to first party at the end of the redirect until ShopifyPOS.init() is called again.

POS Flash Notice

Note

The equivalent action in Shopify App Bridge is Toast.

Displays a message in Shopify POS styled as a notice. Use only for successful or neutral messages. Available in all integrations.

POS Flash Error

Note

The equivalent action in Shopify App Bridge is Toast with the isError option set to true.

Displays a message in Shopify POS styled as an error. Use only for errors or failures. Available in all integrations.

POS Fetch User

Note

There is no equivalent method in Shopify App Bridge. User data can be accessed using the app.getState() method.

Corresponds to the user who entered their PIN on the POS. Available in all integrations. The result passed to the success callback is an object with the following properties:

Key	Type	Description
id	Number	The unique identifier of this user.
first_name	String	The first name of the user.
last_name	String	The last name of the user.
email	String	Email address of the user.
account_owner	Boolean	Returns either true or false, determining if the currently logged in user is the account owner.
user_type	String	Returns either regular or restricted. A regular user has Admin and POS privileges, while a restricted user only has POS privileges.

POS Fetch Location

Note

There is no equivalent method in Shopify App Bridge. Location data can be accessed using the app.getState() method.

Corresponds to the currently-set location of the POS. Available in all integrations. The result passed to the success callback is an object with the following properties:

Key	Type	Description
id	Number	A unique numeric identifier for the location.
name	String	The name of the location.
address1	String	The first line of the address.
address2	String	The second line of the address.
zip	String	The zip or postal code.
city	String	The city the location is in.
province	String	The province the location is in.
country_code	String	The country code the location is in.
country_name	String	The name of the country which the location is in.
phone	String	The phone number associated to the location.
active	Boolean	Returns either true or false, determining if the current location is active.

POS Close Modal

Note

There is no equivalent action in Shopify App Bridge.

Closes the currently open app, and returns the user to Shopify POS.

Cart Fetch

Note

The equivalent action in Shopify App Bridge is Cart.

Retrieves the currently active cart on the POS. Only available in the Edit Cart integration. The result passed to the success callback is an object with the following properties:

Key	Type	Description
line_items	Array	A list of lineitem objects. Can be used with Integrations to update or remove existing lineitems.
properties	Array	A list of arbitrary cart properties. These properties may have been added by other embedded apps.
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.
tax_total	String	The sum of taxes for the current cart. Value is based on the shop's existing currency settings.
grand_total	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.
cart_discount	Object	The current discount applied to the entire cart. This object is in the form {amount: ..., description: ...}.
customer	Object	The customer associated to the current cart. If there is no customer on the cart, returns undefined.

Example usage:

Tip

For the following examples, cart is assumed to be the argument passed into the success callback for ShopifyPOS.fetchCart()

Cart Set Customer

Note

The equivalent action in Shopify App Bridge is Cart.

Sets a customer on the current cart. This method is available only in the Edit Cart integration. The expected behavior of this method depends on the customer information that's provided.

When providing a customer id from the Shopify Admin API:

• Setting an invalid id will throw an error.
• If an ID is provided, the ID is for an existing customer, and a valid email is provided, then the existing customer email will be updated. If the specified email is already taken by an existing customer, then an error will be thrown.
• If an ID is provided, the ID is for an existing customer, and the first_name, last_name, or note is provided, then the existing customer will be updated with the provided fields.

When providing a customer email without an id:

• Setting a unique email will create a new customer. If the first_name, last_name, or note are provided, then the new customer will have those attributes.
• If the specified email is invalid or already taken by an existing customer, then an error will be thrown.
• If an existing customer email is provided, then setting the first_name, last_name, or note will update the existing customer with the provided fields.

When providing a customer without an id or email:

• Setting a first_name or last_name will create a new customer.
• Since first_name or last_name are not required to be unique, setting a customer with these fields will generate a new customer each time the method is invoked.

Key	Type	Description
id	Number	The unique numeric identifier for the customer, according to the Shopify Admin API. Required if none of the other fields are provided.
email	String	The customer's email address.
first_name	String	The first name of the customer.
last_name	String	The last name of the customer.
note	String	A note to store on the customer's account.

Example usage:

Cart Remove Customer

Note

The equivalent action in Shopify App Bridge is Cart.

Removes the customer on the current cart. Only available in the Edit Cart integration.

Cart Add Customer Address

Note

The equivalent action in Shopify App Bridge is Cart.

Adds a new address for the customer associated with the current cart. This method will fail if there is no customer on the cart. It's available only in the Edit Cart integration.

Key	Type	Description
address1	String	The customer's primary address.
address2	String	Any associated information to the address (Apartment #, Suite #, Unit #, etc.).
city	String	The name of the customer's city.
company	String	Optional: Company name associated with address.
first_name	String	The first name of the customer.
last_name	String	The last name of the customer.
phone	String	The customer's phone number.
province	String	The province or state of the address.
country	String	The country of the associated address.
zip	String	The ZIP or postal code of the address.
name	String	The name of this address.
province_code	String	The acronym of the province or state.
country_code	String	Country Code in ISO 3166-1 (alpha-2) format. See Current ISO Codes.

Example usage:

Cart Update Customer Address

Note

The equivalent action in Shopify App Bridge is Cart.

Updates an address for the customer associated with the current cart. index is the position of the address in cart.customer.addresses, and is required. For the list of valid attributes, see the description of addCustomerAddress(). This method is available only in the Edit Cart integration. Provide null or empty string as values to clear out fields.

Example usage:

Cart Set Discount

Note

The equivalent action in Shopify App Bridge is Cart.

Adds a discount to the current cart. Only available in the Edit Cart integration.

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.
discount_description	String	A description of the discount being applied. Defaults to Discount, if not supplied.
type	String	Options are flat or percent. Defaults to flat, if not supplied.

Example usage:

Cart Remove Discount

Note

The equivalent action in Shopify App Bridge is Cart.

Removes the discount on the current cart. Only available in the Edit Cart integration.

Cart Add Properties

Note

The equivalent action in Shopify App Bridge is Cart.

Adds String properties to the current cart. These are similar to line item properties, but are applied to the entire cart. This method is available only in the Edit Cart integration. Adding null keys or values will be ignored.

Example usage:

Cart Remove Properties

Note

The equivalent action in Shopify App Bridge is Cart.

Removes one or more properties from the current cart. propKeys is an array of properties to be removed based on their key. This method is available only in the Edit Cart integration.

Example usage:

Cart Clear

Note

The equivalent action in Shopify App Bridge is Cart.

Removes all line items, properties, discounts, and customer information from the cart. Only available in the Edit Cart integration.

Add Line Item

Note

The equivalent action in Shopify App Bridge is Cart.

Adds a new line item to the current cart. Only available in the Edit Cart integration. This method allows you to add a new custom line item to the cart, or update an existing line item quantity if conditions are met:

When adding new line items:

• Product variant: Providing an existing variant_id with quantity will add that variant to the cart and set its quantity.
• Custom sale: Providing price, quantity, title will create a new custom sale line item and add it to the cart.

When updating existing line items:

• Product variant: Providing an existing variant_id (already in the cart), and quantity will increment the line item's quantity.
• Custom sale: Providing an existing price and title will increment the line item's quantity.

Key	Type	Description
price	Number	The price of the line item. Required if a variant_id 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.
variant_id	Number	The unique ID of the variant being added. If not included, the product will be considered a custom sale.

Example usage:

Update Line Item

Note

The equivalent action in Shopify App Bridge is Cart.

Updates an existing line item quantity in the cart. index is the position of the line item in cart.line_items and is required. We only support updating the quantity for line items in the cart. You must add a new custom sale line item that is a duplicate of an existing cart line item if you wish to change the price and title, then manually remove the duplicated (outdated) line item from the cart. See the description of addLineItem() for the list of valid attributes. Only available in the Edit Cart integration.

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

Example usage:

Remove Line Item

Note

The equivalent action in Shopify App Bridge is Cart.

Removes an existing item from the cart. index is the position of the line item in cart.line_items and is required. Only available in the Edit Cart integration.

Example usage:

Set Line Item Discount

Note

The equivalent action in Shopify App Bridge is Cart.

Sets the discount on a line item in the current cart. index is the position of the line item in cart.line_items and is required. Only available in the Edit Cart integration.

Key	Type	Description
amount	String	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 and 1.
discount_description	String	A description of the discount being applied. Defaults to Discount, if not supplied.
type	String	Options are flat or percent. Defaults to flat, if not supplied.

Example usage:

Remove Line Item Discount

Note

The equivalent action in Shopify App Bridge is Cart.

Removes a line item discount in the current cart. index is the position of the line item in cart.line_items, and is required. This method is available only in the Edit Cart integration.

Add Line Item Properties

Note

The equivalent action in Shopify App Bridge is Cart.

Adds a String property to a given line item in the current cart. index is the position of the line item in cart.line_items, and is required. This method is available only in the Edit Cart integration. Adding null keys or values will be ignored.

Example usage:

Remove Line Item Properties

Note

The equivalent action in Shopify App Bridge is Cart.

Removes a property from a given line item in the current cart. index is the position of the line item in cart.line_items and is required. propKeys is an array of properties to be removed based on their key. Only available in the Edit Cart integration.

Example usage:

Errors

Note

The equivalent method in Shopify App Bridge is app.error.

Type	Description
persistence	This error can occur when trying to fetch or update the current Cart object. It means that the read or write operation on the Cart object failed and you can try repeating the operation that failed.
authorization	This error occurs when your application failed to authenticate with Shopify because the client ID was missing or incorrect.
validation	This error occurs when there was a problem validating the JSON data that was sent as part of your request payload. The error details will contain specific information about which field failed validation.
network	This error is similar to the persistence error but instead of an issue with the device storage it indicates a problem with a network call to Shopify's server. You can try repeating the operation that failed.
unsupported_operation	This error occurs when you are trying to use a Cart method from a POS screen other than the Edit Cart screen.