#Connecting Shopify

For a merchant on Shopify. Installing the app is most of the integration: your catalog, customers and orders sync on their own, and the app tells you which storefront widgets your theme already has and offers to add the rest.

#Installing

Install the Cascade app from your Shopify admin. The first thing it asks is which Cascade organization to connect the store to, before Shopify asks you to approve anything. Sign in, pick the organization, and approve the permissions Shopify then shows you.

When you land back in Cascade the store is connected. Three things have already happened:

1. A site was created for the store, named after it. Everything the store syncs belongs to that site.
2. Webhooks were registered with Shopify, so future changes arrive on their own.
3. A backfill started, importing your existing products, customers and orders.

One shop connects to one Cascade organization. If you run several shops, connect each of them to the same organization and they arrive as separate sites.

#The first sync

The backfill runs through the same import pipeline as a CSV upload, in the order products, customers, orders, because each references the last. Watch it under Settings → Imports: you get progress, the source file, and any rows that could not be read with the reason.

A big catalog takes a while. Nothing is blocked in the meantime, but reviews and loyalty have nothing to attach to until the products land, so it is worth letting it finish before you set flows up.

#What stays in sync afterwards

The product handle is the identity, which matters in one specific way: renaming a handle in Shopify makes a new product in Cascade rather than renaming the existing one. The reviews on the old handle stay with the old product. Rename handles rarely, and check what happened to the reviews afterwards if you do.

Marketing consent syncs one way. A customer explicitly unsubscribed in Shopify is opted out in Cascade; every other state leaves the Cascade flag alone, and Cascade never writes its own opt-out back to Shopify.

#Reading Shopify metafields into Cascade

Your store probably keeps things in metafields that Cascade would find useful: a product's material, a customer's lifecycle stage, an order's gift message. You choose which of them come across. Open the sync settings dialog under Settings → Integrations and add a mapping under Metafields synced in: pick whether it applies to products, customers or orders, name the metafield's namespace and key, and choose the metadata key it is saved under.

From then on, whenever a record syncs, the mapped values land in that record's metadata in Cascade. They show up everywhere metadata does: on the record's page, in filters (for example metadata.lifecycleStage), and in exports.

A few things worth knowing:

• Values are stored as text. A metafield that holds structured data, such as a JSON value or a list, is stored as its serialized text rather than skipped.
• Keys that belong to the connector, such as shopifyCustomerId, cannot be mapped onto. The dialog tells you if you try.
• Syncing merges into metadata rather than replacing it, so keys you set yourself are never lost to a sync.
• Removing a mapping stops future updates but leaves the last synced value in place. Use the bulk metadata actions on the customers, products or orders list to clear it.
• Metafield changes are picked up on their own for the namespaces you have mapped, along with the record's regular updates and any re-sync. Up to 50 metafields are read per record.

#Deletion settings

When a product, customer or order is deleted in Shopify, you decide what happens to the Cascade record. Each of the three has its own setting, under Settings → Integrations or on the connector page inside Shopify. Both screens edit the same thing.

A product or customer that is also linked to another site is only unlinked, never destroyed, whichever setting you choose.

Reviews outlive the product or customer they describe. Deleting either detaches the review and unpublishes it rather than deleting it, and the dashboard shows "Deleted product" on the row. If you would rather reviews went with the record, turn on Delete reviews with their product or customer under Settings → Reviews.

Shopify's customer redaction requests are honored in full regardless of these settings, because they are a legal obligation rather than a preference.

#Loyalty earning from synced orders

Synced orders can earn loyalty points and stamps like any other order. Two settings in the sync settings dialog under Settings → Integrations decide when:

• Orders earn chooses whether an order earns as soon as it arrives (On creation) or only once Shopify reports it paid (When paid).
• Earn on the first sync and re-syncs is off by default, so importing years of order history does not mint years of points. Turn it on only if you want the backfill to earn.

#Loyalty rewards become real discount codes

On a connected store, a reward a member claims is minted as an actual Shopify discount, so the code works at checkout without you doing anything. This is the main practical difference between running loyalty on Shopify and running it on a custom storefront, where you apply the discount yourself.

Which store a reward belongs to is worked out through the loyalty program's sites, so attach your program to the right site under Loyalty → Settings if you run more than one.

#Loyalty at checkout

Cascade ships a checkout block you place in Shopify's checkout editor, the same way Smile or LoyaltyLion do it. Open Settings → Checkout in your Shopify admin, press Customize, and add the Cascade loyalty block where you want it, usually in the order summary column.

What a buyer sees depends on who they are:

• A signed-in member sees their points balance and tier, roughly what the order they are about to place will earn, any reward codes they already hold with a one-tap Apply, and a Redeem control that spends points on a reward right there. Redeeming mints the discount and applies the code to the checkout in one step.
• A signed-in shopper who has not joined sees what the order would earn and a nudge to join on the store.
• A guest sees what the order would earn and a prompt to sign in. Guests can never spend points, because checkout cannot prove who they are.

The earning number is an estimate and the block says "about". Rules limited to specific products and per-member limits are only judged when the order actually lands, so the final award can differ.

The block has two settings in the checkout editor: a heading (it uses your program's name if you leave it empty) and an API URL override you can normally leave alone. If your program is paused the block says so and keeps the balance visible; if the store has no published program the block renders nothing at all.

Checkout blocks require Shopify Plus for the checkout itself, per Shopify's own rules; on other plans you can still place the block on the thank-you and order status pages.

#Widgets in your theme

The Cascade app inside Shopify has a Widgets in your theme card. It reads your live theme, lists every widget, and says whether the theme has it, has it but switched off, or does not have it. Nothing there edits your theme: Add opens your theme editor with the block already placed, and you decide where it goes and press Save.

Two of those are worth explaining.

The Cascade embed is the one that loads everything else, so turn it on first. It also carries the settings that apply everywhere: the floating rewards button and whether a page view counts as a loyalty visit.

The loyalty launcher is a switch on the embed, not a block of its own. A block lives in one template, and a floating button that only appears on your home page is not much use.

Product slugs are Shopify handles, which the blocks fill in for you. See Storefront widgets for what each widget does and the settings it takes.

#How a shopper's own wishlist and balance work

The wishlist widgets, and a member's own points and rewards, are private to one shopper, so they need a signature Cascade makes with your signing secret. On other platforms you generate that on your own server. On Shopify you do not have to: the app answers for the signed-in shopper on Cascade's own servers, through your store's own domain, and the theme never sees the secret. A shopper who is not signed in sees the public half (ratings, reviews, the program itself) and your store's usual sign-in prompt.

A shopper who signed up in Shopify seconds ago works too. If Cascade has not synced them yet, the app looks them up in Shopify once and remembers them.

#If your theme is older

Themes from before Online Store 2.0 do not support app blocks at all. The card says so and offers Add by hand instead, which shows the Liquid to paste into your theme, already filled in with your publishable key. Everything works the same afterwards; you just place it yourself.

#If Cascade asks for theme access

Reading your theme needs a permission Cascade did not ask for when you first connected, so a store connected before this feature shipped sees Grant theme access on the card instead of the widget list. It is a read-only permission and it takes one click. Until you grant it, the widgets still work, they just have to be added by hand.

Cascade re-reads your live theme once a day, so switching theme shows up on the card without you doing anything.

#Ratings as product metafields

Cascade also writes each product's review count and average rating back to Shopify as metafields, so you can use them in Liquid and in anything that reads Shopify data directly (search and filtering apps, feeds, Google Shopping).

Both are readable from the storefront, so a theme can use them without an app proxy:

{% assign rating = product.metafields.cascade.review_average %}
{% if rating %}
  <span>{{ rating }} out of 5 ({{ product.metafields.cascade.review_count }})</span>
{% endif %}

They are filled in during the first sync for any product that already has reviews in Cascade, and updated whenever a review is published, edited or removed. A product with no published reviews has no metafield at all rather than a zero, so check for it the way the example above does.

#Loyalty as customer metafields

Cascade also writes each member's loyalty state to their Shopify customer record, so you can use it in Liquid, in email tools that read Shopify data, and in customer segments.

Both update within moments of the member earning, spending or changing tier. A member with no tier has no loyalty_tier metafield at all, so check for it before rendering:

{% if customer.metafields.cascade.points_balance %}
  <p>You have {{ customer.metafields.cascade.points_balance }} points.</p>
{% endif %}

Liquid only exposes the signed-in customer's own record, so a shopper can only ever see their own balance.

#Paying for Cascade

If you installed Cascade from the Shopify app store, Shopify bills you: your plan is a line on your Shopify invoice alongside your other apps, and you approve the charge in your Shopify admin before anything is billed. The Cascade app inside Shopify shows the plan and what it costs, and so does Settings → Billing in Cascade.

If you were already paying Cascade by card before connecting a store, that does not change, and nothing is added to your Shopify bill. See Billing for the whole picture, including where to change plan.

#Disconnecting

Disconnecting stops the sync. Your data stays in Cascade: the site, its products, customers, orders and every review and loyalty balance attached to them. Reconnecting the same shop picks up where it left off.

Uninstalling the app from Shopify does the same thing from the other side, and it also ends the Shopify charge if that is how you were paying.

#If something is not syncing

1. Check Settings → Imports for the backfill and its errors.
2. Check Settings → Integrations for the connection's status.
3. Try the record itself. A product with no handle, or an order referencing a product Cascade has never seen, is skipped and reported rather than guessed at.
4. Check your plan limits. Connecting a store creates a site, and an organization at its site limit cannot connect another. See Plans and limits.