Shopify setup and testing

This guide covers the complete setup path for the Smartix Shopify app. Work through it in a development store first, then repeat the relevant checks in the store you will use for customers.

Caution

You need a Smartix account and a Smartix API key before you can initialise the Shopify app. Create a dedicated API key for Shopify; do not share a key used by another integration.

Setup at a glance

Complete these steps in order:

1. Install the Smartix app from the Shopify App Store.
2. Connect the app to Smartix with a TEST API key.
3. Choose whether the store uses Smartix on the storefront, in POS, or in both.
4. Enable the pass types and configure membership tiers in Manage pass types.
5. Tag eligible products, unless you have enabled the all-products option.
6. Enable the storefront blocks and customer-account link when using online features.
7. Enable the POS extension and add the Smartix tile when using POS features.
8. Use the setup checks on the app home page, then run the end-to-end tests below.

1. Connect the Smartix API

1. In Smartix Studio, open Account > API keys and create a TEST/LIVE key pair for Shopify.
2. In Shopify admin, open the Smartix app and choose Setup.
3. Paste the TEST key and save it. The app verifies the key and stores the associated Smartix client for the shop.
4. Confirm that the setup status changes to API Connected and that the key is shown as verified.

Use the TEST key while configuring and testing. Test passes are kept separate from live customer passes. Switch to the LIVE key only after the review and acceptance checks are complete.

2. Choose how Smartix is used

On the app setup page choose one of:

• Storefront for online store and customer-account features;
• POS for in-store scanning and checkout actions; or
• Both for a combined online and in-store installation.

The setup checker uses this choice to show the checks that apply to your store. Changing the choice does not itself enable a pass type or publish a theme block.

3. Configure pass types

Open Manage pass types in the Smartix app. Enable the pass types needed by the store and choose separately whether each is available in POS and online surfaces.

Supported pass types include loyalty cards, stamp cards, membership cards and gift cards. Stamp cards are currently a POS workflow; do not expect them to appear in the customer-account extension.

If membership cards are enabled, configure each membership tier and its discount percentage. The tier key returned by Smartix must match the tier used by the membership pass.

4. Tag eligible products

Product tags control which products participate in each feature:

Feature	Product tag
Loyalty points	SX_LOYALTYCARD_ELIGIBLE
Stamp earning and redemption	SX_STAMPCARD_ELIGIBLE
Membership discounts	SX_DISCOUNTCARD_ELIGIBLE

Add tags in Shopify admin on the products that should participate. The setup page reports how many tagged products it finds. For loyalty, membership and other supported options, you can instead enable the corresponding all products setting in the app where available.

Take care when combining features. If a product is eligible for more than one scheme, configure the exclusions in Manage pass types so customers do not earn overlapping benefits unintentionally.

5. Storefront setup

These steps apply when usage is set to Storefront or Both. Theme names vary, so the labels below may be slightly different in a custom theme.

Customer account

Add a link to the customer account menu:

1. In Shopify admin, open Content > Menus.
2. Select Customer account main menu and choose Add menu item.
3. Give the link a label such as Store cards.
4. Choose Link > Apps > Smartix Customer Account, then save.
5. In Online Store > Edit theme, open Checkout and customer accounts, select the customer profile, open Apps, and add Smartix Customer Account to the account page.

Signed-in customers can then request or connect supported cards, view balances and history, and install Apple Wallet or Google Wallet passes. Membership cards can be connected but are issued by the retailer rather than requested by the customer.

Product page membership block

If membership discounts are enabled, open the product template in the theme editor and add the Smartix member prices app block. Place it near the normal price and buy buttons. It displays the configured membership pricing when the customer has a valid membership card.

Cart page

For online loyalty redemption and earned-points information:

1. Set the cart type to Page rather than drawer.
2. Add the Smartix cart block to the cart template.
3. Enable the Smartix cart app embed in the theme editor.
4. Save and preview the cart with a customer account that has a valid loyalty card.

Shopify does not expose the same cart controls on every checkout. The standard integration therefore performs loyalty redemption on the cart page; a checkout-specific implementation may require Shopify Plus.

6. POS setup

These steps apply when usage is set to POS or Both:

1. In Shopify admin, open Point of Sale > Settings > POS App and enable the Smartix app.
2. Open the POS editor and add the Smartix home tile to the POS smart grid.
3. Restart or refresh the POS app and confirm the tile reports Ready to scan.

The POS tile can scan a wallet barcode using the device camera or a supported external scanner. A valid pass is added to the cart. Staff can then apply the actions supported by the pass type, such as earning points or stamps, redeeming loyalty points, redeeming full stamp cards, or applying membership discounts.

7. End-to-end test checklist

Use TEST passes and a test customer until every applicable check passes.

Customer account and wallets

• Open the customer-account link while signed in as a test customer.
• Request a loyalty card where that feature is enabled.
• Connect an existing pass by entering its pass ID.
• Install the pass in Apple Wallet and Google Wallet.
• Confirm the displayed balance, tier or expiry matches Smartix Studio.

Storefront

• Open a tagged product as a customer with a valid membership card and confirm the member price block appears.
• Add eligible products to the cart and confirm the loyalty points preview.
• Select a loyalty redemption and confirm the cart discount is applied.
• Change the cart contents and confirm an invalid redemption is cleared or recalculated.
• Complete a test order and confirm the Smartix balance and wallet pass update afterwards.

POS

• Scan a loyalty, stamp or membership pass with the Smartix tile.
• Confirm the pass appears in the cart.
• Complete a loyalty redemption or stamp-card redemption where applicable.
• Confirm membership discounts are applied to tagged products.
• Complete checkout and verify the pass update and balance change on the device.

Setup checker and troubleshooting

The app home page includes checks for API connectivity, initialisation, enabled pass types, membership tiers, product tags, storefront blocks, cart configuration, the customer-account menu link and the POS home tile. Use Refresh checks after changing Shopify theme or POS settings.

If a check fails:

• confirm that the app is connected to the intended Smartix client;
• confirm the required pass type is enabled for the selected usage mode;
• check product spelling and tags exactly, including capitalisation;
• make sure the cart uses a page template and the Smartix embed is enabled;
• confirm the POS extension is enabled and added to the smart grid; and
• test with a fresh TEST pass and a customer account rather than a previously cached session.

For API details, see the Smartix API guide. For a workflow that is not covered here, contact Smartix support.