Getting started

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

Ruby on Rails example app

Shopify has published a sample POS embedded app on GitHub. This app uses Ruby on Rails and it demonstrates many of the methods and capabilities of the SDK. You can clone this app locally and use ngrok to try it out using an iPad. Find out more about how to use the example POS app.

Contents of the SDK

The POS App SDK offers you a ShopifyPOS JavaScript API. This API wraps the underlying iOS WebView and provides native tie-in support for:

  • Cart modifications (e.g adding/removing line items, discounts, custom properties)
  • Alert, confirm, and input dialogs
  • Flash messages
  • Modals
  • User and location information.

Learn about the methods that are available using the POS App SDK.

Creating an app that uses the Shopify POS App SDK

First, follow the Getting Started guide to create a development store and an app.

After you have a partners account and an app, in the Partners Dashboard:

  1. Click Apps in the sidebar.

  2. Click the name of your app.

  3. Click Extensions:

App extensions

  1. In the Embedded in Shopify POS section, click Embedd in POS.

  2. Save your changes.

HTTPS, SSL certificates and mixed content restrictions

Shopify POS uses SSL for all of its communication. Security of financial data requires all embedded apps to also run on HTTPS.

Like embedded apps in the Shopify admin, publishing an embedded app in the Shopify App Store requires the app to have an SSL certificate.

OAuth

OAuth will behave normally in your app, as it would for any other Shopify apps or other OAuth enabled services with one caveat:

Since the application is loaded inside an iframe it is critical that the initial OAuth request redirect escapes the iframe to make the requests. Shopify returns the X-Frame-Options=DENY header and prevents any Shopify admin pages from being loaded inside an iframe.

This means that where the OAuth process would normally begin with:

redirect_to "/auth/shopify?shop=myshopname"

It should now return a page containing:

<script type="text/javascript">
  window.top.location.href = '/auth/shopify?shop=myshopname';
</script>

The above example assumes you're using the Shopify Omniauth gem. If not, replace /auth/shopify with the supported http://myshop.com/admin/oauth endpoint.

Read more about how to use OAuth with Shopify ›

Initializing the POS App SDK

To expose the JavaScript API to your app, simply include the pos_app.js script at the top of your app's <head> element. It has no dependencies but plays well with other libraries like jQuery.

<head>
  <script src="https://cdn.shopify.com/s/assets/external/pos_app.js"></script>
  ...
</head>

Initialize the SDK using your API key and your https://example-store.myshopify.com URL immediately after including the pos_app.js file:

<head>
  <script src="https://cdn.shopify.com/s/assets/external/pos_app.js"></script>
  <script type="text/javascript">
    ShopifyPOS.init({
      apiKey: 'YOUR_APP_API_KEY',
      shopOrigin: 'https://CURRENT_LOGGED_IN_SHOP.myshopify.com'
    });
  </script>
  ...
</head>

This makes the ShopifyPOS object available and ready for use.

The script detects if your app was loaded inside an iframe. If not, it will create a redirection back into the relative embedded URL in the Shopify admin. This functionality can be disabled by passing forceRedirect: false as a configuration option.

You can include a debug: true option as well to get detailed output into console.log for browsers that support it.

Once your app has been initialized, the callbacks passed to ShopifyPOS.ready() are called. There is no guarantee that communication with POS is possible before ready() is called. Here is a sample inline script for an embedded app view:

<script type="text/javascript">
  ShopifyPOS.ready(function(){
    //App view is now rendered
    ShopifyPOS.flashNotice('Hello world!');
  });
</script>

The initialization step is required on any page shown embedded in POS. The callback from ready() must be done if any API integration with POS is desired.

Once initialized, you can use any of the API methods and features provided with the Shopify POS App SDK.

Learn more about API methods ›

Selling your POS app in the Shopify App Store

After you have written an embedded app for Shopify POS, you may want to submit it to the Shopify App Store. You can bill merchants for your app using Shopify's Billing API. Merchants can buy your app using the Billing API when they access your app using the Shopify web admin. Billing API requests cannot be made from within the POS itself. Find out about how to get your app listed in the Shopify App Store.