Set up Linesman on your Shopify store

1. Install and get your Bot Receipt

Install Linesman and approve the permissions. Linesman starts with a read-only scan of the last 90 days: it only reads data, and nothing changes in your store.

• Bot checkouts and bot customers found in the last 90 days.
• Estimated costs: card-testing fees (enter your payment provider's fee per declined attempt to see this), the Klaviyo cost of fake profiles, and the time to clean up by hand. Each estimate shows its formula.
• The real-order check: "Of your real orders in the last 60 days, our rules would have flagged…". If any real order would have been flagged, review it and choose "These are real — always allow them" before you turn on blocking.

You can rescan once every 7 days on Free, and daily on Pro.

2. Turn on Linesman Shield in your theme

The Shield adds an invisible browser check to real shoppers' carts. It's an app embed, so there's no theme code to edit. It's tiny, loads after the page, starts its check only when the shopper interacts, and never changes what shoppers see.

1. In setup step 3, click Turn on in theme editor. Your theme editor opens in a new tab with the Linesman Shield embed switched on.
2. Click Save in the theme editor.
3. Come back to Linesman. The card turns green once Shopify reports the embed as on. You don't need to visit your store.

Changed or updated your theme? App embeds start switched off in a new theme. Linesman shows a banner when the Shield is off; click "Turn on Shield in theme editor" and save.

In the same step, Linesman creates its checkout guard in Shopify (Settings → Checkout → Checkout rules) in Watch mode.

3. Watch mode: see the proof first

Linesman checks every checkout and records what it would have blocked, but lets every order through. Rows marked "Would block" in Activity are bots that got through this time.

Within 7 days (or sooner, after 20 would-block checkouts and at least 48 hours) you get your verdict by email: how many bot checkouts Linesman spotted and how many real orders would have been affected. Linesman only recommends turning on protection when that number is zero; otherwise it lists the orders to review first.

Under attack right now? You don't have to wait for the verdict. Turn on Balanced protection straight away.

4. Turn on protection

1. Go to Settings → Protection mode.
2. Choose Balanced (recommended, included in Free) or Strict (Pro).
3. Confirm. The dialog shows what Linesman would have stopped during your watch period and how many real orders it would have affected.

You can switch back to Watch at any time. Returning customers, your allow list and recent buyers always pass in every mode.

A stopped shopper sees this message at the payment step: "We couldn't confirm this checkout. Please refresh the page and try again. Need help? Contact {your store email}." On Pro you can change the wording in Settings.

5. Attack mode

Linesman watches for bursts of bot checkouts. When an attack starts, you get an email, and on Pro, Attack mode turns on automatically: checks get stricter, shoppers' browsers solve a small background puzzle, and emails, phones and addresses that repeat across bot checkouts are blocked for 24 hours. It turns off on its own after the attack ends, and you get a summary email.

• Turn automatic Attack mode off, or change the puzzle strength (Light, Normal, Strong), in Settings.
• Start Attack mode by hand for 1, 4 or 24 hours from the dashboard. It needs Balanced or Strict protection.

6. Activity: every decision explained

Activity lists every scored checkout with a masked email, the cart total and a plain-English reason, such as "No browser check", "Throwaway email" or "Placeholder name". Open a row to see every reason and act on it:

• Always allow this buyer: adds their email and address to your allow list.
• Block this buyer: blocks their email, phone and address.
• This was a real customer / This was a bot: keeps your numbers right. It doesn't allow or block anyone by itself.

Free shows the last 7 days of activity; Pro shows 90 days.

7. Allow and block lists

• Add buyers to the allow list from Activity or Settings, or tag a customer linesman:allow in Shopify. Allowed buyers always pass.
• Block lists fill automatically when emails, phones or addresses repeat across bot checkouts, and you can add entries by hand. Entries are stored as one-way hashes, never as readable emails or addresses.

8. Clean up fake customers

1. Open Cleanup. Bot customers are grouped into Bots (selected), Likely bots (not selected) and Protected (customers with orders or the allow tag, never touched).
2. Click Download backup to get a CSV of your selection.
3. Choose Delete or Tag (adds the tag linesman:bot), and type the number to confirm.

Free deletes up to 250 customers a month and tags any number; Pro has no limit. On Pro you can also turn on Auto-clean new bot signups: new bot accounts are tagged right away and deleted after 24 hours if they still have no orders.

9. Connect Klaviyo or Omnisend (Pro)

In Cleanup, paste a Klaviyo private API key with these scopes: Profiles (read), Subscriptions (write). Linesman uses it only to suppress profiles it identifies as bots, and you can disconnect at any time (the key is deleted immediately).

• Bot customers are suppressed in Klaviyo before they're deleted in Shopify, so they stop counting toward your Klaviyo bill. If suppression fails, nothing is deleted.
• Linesman checks new Klaviyo profiles every 15 minutes and lists bot signups from your Klaviyo forms. Suppress them, or mark any as "Not a bot".
• Omnisend: paste an API key with Contacts read and write access. When you suppress or delete bot customers, Linesman unsubscribes the same emails in Omnisend.

10. Optional rules for free items and bait products

• Require a paid item (off by default): stops carts where every item is free. Leave it off if you give free items on purpose.
• Bait product (off by default): create a cheap product real shoppers never see, keep it out of collections, menus and search, and tag it linesman:bait. Bots that scrape your catalog grab it, and any checkout containing it is blocked.

Both rules only block in Balanced or Strict mode. In Watch mode they're recorded. Customers with past orders and your allow list are never affected.

11. Alerts and emails

• Attack started and Attack over: when an attack begins (at most once every 6 hours) and a summary when it ends.
• Watch-week verdict: once per watch period.
• Weekly receipt every Monday, which you can turn off in Settings.
• Shield needs attention: if the checkout guard is turned off, the Shield looks off, or settings can't be updated.

Free sends alerts to 1 recipient, Pro to up to 3. Set them in Settings.

Troubleshooting

• "Shield is off in your current theme": usually after a theme change. Click "Turn on Shield in theme editor", then Save.
• "Checkout guard is turned off in Shopify": someone switched off the Linesman checkout rule in Shopify. Use the fix link in Help or Settings. If the rule was deleted, Linesman recreates it within an hour.
• "We couldn't update your checkout guard. Retrying.": Linesman retries on its own; the last saved settings keep working meanwhile.
• A real customer was stopped: they can refresh and try again. In Activity, choose "This was a real customer" and "Always allow this buyer", and we'll look into it.

The Help page in the app shows a live status check for each part, with a fix link for anything that isn't working.

For developers: the status API

Linesman has no public API for store data: you use it inside your Shopify admin. For uptime monitors, two public, read-only endpoints return JSON and no store or customer data.

• GET /healthz: 200 with status "ok" when the web service and its database are up, 503 with status "degraded" otherwise.
• GET /healthz/worker: 200 with status "ok" and the heartbeat age in seconds when the background worker is running, 503 when it is "stale", "missing" or "unknown".

Machine-readable descriptions: the OpenAPI 3.1 file and the API catalog (RFC 9727).