Methods

There are a number of methods that can be used on the ShopifyPOS integrations. The following chart links to example code, and displays which integrations can access which methods:

Name Description Edit Cart Order complete
POS Dialog Standard browser dialog support.
POS Callbacks Callbacks and error handling.
POS Initialize
POS Ready
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 merchant 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
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

Many of the methods in the POS Embedded 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:

// method signature is ShopifyPOS.fetchCart(callbacks)

ShopifyPOS.fetchCart({
  success: function(cart) {
    // argument will vary based on the function (e.g. Cart in this example)
  },
  error: function(errors) {
    // errors is an array of errors in the format:
    // [{property: ..., message: ..., errorType: ...}]
  }
});

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 a 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

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 API key provided to you for your application in the Shopify Partners area.
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 merchant/shop. 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.
ShopifyPOS.init({
  apiKey: "ff9b1d04414785029e066f8fd0465d00",
  shopOrigin: "https://example.myshopify.com",
  debug: false,
  forceRedirect: true
});

POS Ready

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.

ShopifyPOS.ready(function(){
  alert("Ready");
});

POS Flash Notice

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

ShopifyPOS.flashNotice("Unicorn was created successfully.");

POS Flash Error

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

ShopifyPOS.flashError("Unicorn could not be created.");

POS Fetch User

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.

POS Fetch Location

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

Closes the currently open app, and returns the merchant to their POS.

ShopifyPOS.Modal.close()

Cart Fetch

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 Float 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 Float The sum of taxes for the current cart. Value is based on the shop's existing currency settings.
grand_total Float 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:

ShopifyPOS.fetchCart({
      success: function(cart) {
        // read the cart or call any cart functions here
        // e.g. cart.line_items or cart.addLineItem(...)
      },
      error: function(errors) {
        ShopifyPOS.flashError("Failed to retrieve cart")
      }
    });

Note

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

Cart Set Customer

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

Key Type Description
id Number The unique numeric identifier for the customer, according to the Shopify API.
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.setCustomer({
  first_name: "Jane",
  last_name: "Doe",
  note: "Doesn't like bananas"
}, {
  success: function(cart) {
    ShopifyPOS.flashNotice("Successfully added customer to cart")
  },
  error: function(errors) {
    ShopifyPOS.flashError("Failed to add customer cart")
  }
})

Cart Remove Customer

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

Cart Add Customer Address

Adds a new address on the customer associated with the current cart. This method will fail if there is no customer on the cart. Only available 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 Company name associated with address (optional).
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.addCustomerAddress({
  phone: "(613) 555-5555",
  address1: "123 Cherry St.",
  address2: "Apt. 5",
  city: "Ottawa",
  province: "Ontario",
  country: "Canada"
}, {
  success: function(cart) {
    ShopifyPOS.flashNotice("Customer address added")
  },
  error: function(errors) {
    ShopifyPOS.flashError("Failed to add customer address")
  }
})

Cart Update Customer Address

Adds a new address on the customer associated with the current cart. index is the position of the address in cart.customer.addresses and is required. See the description of addCustomerAddress() for the list of valid attributes. Only available in the Edit Cart integration.

Example usage:

cart.updateCustomerAddress(0, {
  phone: "(613) 555-5555"
}, {
  success: function(cart) {
    ShopifyPOS.flashNotice("Successfully updated address on customer.")
  },
  error: function(errors) {
    ShopifyPOS.flashError("Failed to update customer address!")
  }
})

Cart Set Discount

Adds a discount to the current cart. 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. 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.

Example usage:

cart.setDiscount({
  amount: "10.00",
  discount_description: "holiday sale"
}, {
  success: function(cart) {
    ShopifyPOS.flashNotice("Successfully added discount to cart")
  },
  error: function(errors) {
    ShopifyPOS.flashError("Failed to add discount to cart")
  }
})

Cart Remove Discount

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

Cart Add Properties

Adds arbitrary properties to the current cart. Similar to line item properties, but applies to the entire cart. Only available in the Edit Cart integration.

Example usage:

cart.addProperties({
  referral: "Google",
  employee: "472"
}, {
  success: function(cart) {
    ShopifyPOS.flashNotice("Successfully added properties to cart")
  },
  error: function(errors) {
    ShopifyPOS.flashError("Failed to add properties to cart")
  }
})

Cart Remove Properties

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

Example usage:

cart.removeProperties(["referral"], {
  success: function(cart) {
    ShopifyPOS.flashNotice("Successfully removed properties from cart")
  },
  error: function(errors) {
    ShopifyPOS.flashError("Failed to remove properties from cart")
  }
})

Cart Clear

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

Add Line Item

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 String The price of the line item. Required if a variant_id is not provided and must be greater than 0.
quantity Number The amount of items to add. Defaults to 1 if not provided.
title String The name of the product. Required if a variant_id is not provided.
variant_id Number The unique ID of the variant being added. If not included, the product will be considered a custom sale.

Example usage:

cart.addLineItem({
  variant_id: 123456789,
  quantity: 2
}, {
  success: function(cart) {
    ShopifyPOS.flashNotice("Successfully added lineitem to cart")
  },
  error: function(errors) {
    ShopifyPOS.flashError("Failed to add lineitem to cart")
  }
})

Update Line Item

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. Defaults to 1 if not provided.

Example usage:

cart.updateLineItem({
  index: 1,
  quantity: 2
}, {
  success: function(cart) {
    ShopifyPOS.flashNotice("Successfully updated lineitem to cart")
  },
  error: function(errors) {
    ShopifyPOS.flashError("Failed to update lineitem to cart")
  }
})

Remove Line Item

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.

Set Line Item Discount

Sets the discount on a line item in 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. percent discount amounts must be between 0 and 1.
discount_description Number A description of the discount.
type String Options are flat or percent. Defaults to flat.

Example usage:

cart.setLineItemDiscount(0, {
      amount: "5.00",
      description: "Employee discount"
    }, {
      success: function(cart) {
        ShopifyPOS.flashNotice("Successfully added lineitem to cart")
      },
      error: function(errors) {
        ShopifyPOS.flashError("Failed to add lineitem to cart")
      }
    })

Remove Line Item Discount

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

Add Line Item Properties

Adds a 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. Only available from the Edit Cart integration. Example usage:

cart.addLineItemProperties(0, {
  promotion: "1 free item",
  trim: "brown leather"
}, {
  success: function(cart) {
    ShopifyPOS.flashNotice("Successfully added properties to lineitem")
  },
  error: function(errors) {
    ShopifyPOS.flashError("Failed to add properties to lineitem")
  }
})

Remove Line Item Properties

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:

cart.removeLineItemProperties(0, ["promotion"], {
  success: function(cart) {
    ShopifyPOS.flashNotice("Successfully removed properties from lineitem")
  },
  error: function(errors) {
    ShopifyPOS.flashError("Failed to remove properties from lineitem")
  }
})