ALEAN help
Step-by-step guides for setting up and using ALEAN on your Shopify store. If you get stuck, see Support.
1. Install ALEAN
- Open the ALEAN install link we sent you, or find ALEAN in the Shopify App Store.
- Click Install. Shopify shows the permissions ALEAN needs. Approve them.
- ALEAN opens inside your Shopify admin on Get started with ALEAN.
You never need to type your store's address or create a separate login: ALEAN uses your Shopify admin sign-in.
What you'll need: a Shopify store with the Online Store sales channel, and a theme that supports app embeds (any Online Store 2.0 theme, such as Horizon or Dawn).
2. Turn on the ALEAN widget in your theme
The widget is how shoppers reach order tracking, returns and the shopping assistant on your storefront. Shopify keeps app embeds off until you save them, so this step is needed once.
- In ALEAN, go to Home (Get started).
- Under Turn on ALEAN in your theme, click Open theme editor. Your theme editor opens with the ALEAN embed already switched on.
- Click Save in the theme editor.
- Open your storefront. The ALEAN button appears on every page.
To do it by hand: Online Store → Themes → Customize → the App embeds icon in the left bar → switch on ALEAN → Save.
To turn it off: switch the embed off in the same place and save. Uninstalling ALEAN also removes it.
3. Set up returns and exchanges
Go to Returns → Settings. Nothing changes for shoppers until you save.
Who can use returns
- Returns on: the main switch.
- Who sees returns in the widget:
- Nobody (off): returns are hidden from shoppers.
- Only the emails below (testing): only the shoppers whose emails you list can start a return. Use this to try the flow yourself first.
- Everyone: every signed-in shopper.
- Send emails to customers: status emails such as "Request received" and "Pickup scheduled".
Windows and options
- Return window (days) and Exchange window (days), counted from delivery. Items not marked delivered can't be returned by the shopper; you can create a request for them yourself (below).
- Allowed outcomes: which of Refund, Store credit, Exchange (size / colour) and Exchange (different style) shoppers can choose.
- Offer store credit, with an optional Bonus (%) you fund on top. Store credit needs Shopify's new customer accounts.
- Same-product swaps at no charge, Allow a pricier replacement (the customer pays the difference) and Payment window (hours): how exchanges for a different price work. The new item is held until the shopper pays.
- QC required before refunds and replacements: wait until the returned item is checked.
- Merchant-fault reasons: reasons (such as "damaged" or "wrong item") where you cover the costs.
Click Save. If something required is missing, a Before going live box lists it, for example "A return or exchange window is set" or "At least one return reason".
Rules for specific products
Go to Returns → Rules → Add rule to give some products different terms: final sale, a shorter window, photos required, or a review step. A rule can match product IDs, collections, product types, tags, vendors or SKUs. Products without a rule follow your settings.
4. Handle return requests
- Go to Returns. The inbox lists requests by state, such as Under review and Awaiting payment.
- Open a request to see the items, the reason, any photos and the history.
- Use the action at the top. For a pickup, book it with your courier as usual, then use Book pickup to enter its tracking number (AWB); ALEAN follows it from there. For a request that needs your decision, use Review: waive or charge fees, or Decline.
- When the return is processed, the refund or store credit is recorded on the order in Shopify, through Shopify's own returns and refunds.
Create a return yourself: Returns → Create return. Enter the order number, pick the item, the reason and the outcome. Use Override the policy for a case outside your rules (you'll be asked why).
Paid offline: if a shopper paid a price difference outside Shopify, use Mark as paid (collected offline) on the request.
How decisions are made. Eligibility, refund amounts and store credit come from the rules you set, never from an AI model. You can review and override any request.
5. Connect your courier for live tracking
ALEAN shows shoppers live delivery updates from your Velocity account.
- In the Velocity portal, generate an API token.
- In ALEAN, go to Order tracking. Under Velocity account, leave API URL as
https://shazam.velocity.inunless Velocity gave you another, paste the API token, and click Save and verify. ALEAN checks the token with Velocity before saving it, and stores it encrypted. - Under Velocity webhook, copy the Webhook URL and the Bearer token.
- In Velocity → Settings → Webhooks: set Endpoint to the webhook URL, Authentication Method to API Key, paste the bearer token as the API Key, and tick Status Change and Tracking Addition. Save.
Each store uses its own Velocity token. Never paste another store's token.
Without a courier connection, shoppers still see each order's status from Shopify (for example fulfilled or delivered).
6. Connect Judge.me reviews (optional)
If you use Judge.me, ALEAN can read your published reviews so the shopping assistant can answer questions about fit and quality.
- In Judge.me (for this store): Settings → Integrations → View API tokens, and copy the Private API token.
- In ALEAN, go to Reviews, paste it into Private API token, and click Save and verify.
- ALEAN checks the token with Judge.me, then starts syncing reviews. Use Sync now to sync again.
To stop, click Disconnect on the same page. ALEAN only reads published reviews; it never posts or changes reviews.
7. What shoppers see
With the widget on, shoppers tap the ALEAN button on any page to:
- Track an order. They sign in with a one-time code sent to their email, or through your store's customer accounts, and see each order's status and courier updates. They stay signed in to the widget on that device for 30 days unless they sign out in the widget; today, signing out of your store's account doesn't sign them out of it. Rolling out (October 2026): email-code sign-ins last 7 days, and signing out of your store signs them out of the widget too.
- Start a return or exchange, when you've turned returns on for them. Exchanges and store credit are shown alongside refunds, as your settings allow.
- Ask the shopping assistant about products, sizes, fit, delivery and your policies. We're rolling out (October 2026) a line under the Ask bar, on every screen and led by the ALEAN mark, that tells shoppers "ALEAN is AI and can make mistakes · Privacy"; the Privacy link opens your store's privacy policy (or ALEAN's, if you have none), and "How ALEAN uses data" in the widget's menu opens ALEAN's. It answers from your store's products and policies, and can make mistakes.
Shoppers can use all of this without accepting analytics cookies. ALEAN follows the choice they make in your store's cookie banner; see Cookies and consent.
8. The Widget page
Widget shows how shoppers use the widget over a period: conversations, searches, clicks and add-to-carts. Shoppers who decline analytics in your cookie banner aren't counted.
9. Shopper privacy requests
You don't need to do anything special. When a shopper asks you to see or delete their data and you process it in Shopify (Customers → the customer → Request customer data or Erase personal data), Shopify sends the request to ALEAN:
- Data request: ALEAN emails your store's contact email a file of everything it holds about that shopper, for you to send them.
- Deletion request: ALEAN deletes or anonymises their data within 30 days. Refund and store credit amounts stay, without their name, contact details or address, so your accounts still add up.
10. Uninstall ALEAN
- In your Shopify admin, go to Settings → Apps.
- Next to ALEAN, open the menu and click Uninstall.
What happens:
- The widget disappears from your storefront, and billing for ALEAN stops.
- Returns, refunds and store credit that ALEAN processed stay on your orders in Shopify.
- 48 hours later, Shopify asks ALEAN to delete your store's data. We delete it within 30 days, including our copies of your Shopify orders and customers, chats, searches and return photos.
- If you want a copy of ALEAN data first, write to support@alean.ai before uninstalling.
If you reinstall before the deletion, Shopify asks you to approve the permissions and your plan again.