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 Add to Cart 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 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
location_type String The location type. Defaults to "storefront".
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 String The country 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

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 and Add to Cart integrations. 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, before taxes and discounts. 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.
country_name String The full name of the country.

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. 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 total of the discount to apply. Does not accept percentages.
discount_description String A description of the discount being applied.
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 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 and Add to Cart integrations.

Key Type Description
price String The price of the line item. Required if a variant_id is not provided.
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 item in the cart. Only the attributes that should be updated need to be provided. index is the position of the line item in cart.line_items. See the description of addLineItem() for the list of valid attributes. Only available in the Edit Cart and Add to Cart integrations.

Remove Line Item

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

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. Only available in the Edit Cart and Add to Cart integrations.

Key Type Description
amount String The total price of the discount to be applied.
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. Only available in the Edit Cart and Add to Cart integrations.

Add Line Item Discount

Adds a property to a given line item in the current cart. index is the position of the line item in cart.line_items. Only available in the Edit Cart and Add to Cart integrations.

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")
  }
})

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. Only available from the Edit Cart and Add to Cart integrations. 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. propKeys is an array of properties to be removed based on their key. Only available in the Edit Cart and Add to Cart integrations.

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")
  }
})