Koru Power Seller

Social Selling app for VTEX store salespeople — catalog with trackable links and shareable banners, CRM with abandoned-cart detection and a sales ranking, with its own admin panel.

Koru Power Seller (identified in its own code as "Power Seller") is a Social Selling application for VTEX store salespeople: each salesperson gets their own catalog with real prices and stock, generates trackable links and suggested copy to share products on social media or WhatsApp, tracks their sales and their position on a ranking, and manages a client portfolio with protected data. Unlike the rest of Koru's apps, it does not live inside VTEX Admin: it is its own mobile-first web application, hosted separately (Cloudflare Pages) and multi-tenant — a single deployment serves every retailer that contracts it, each with its own brand, its own salespeople and its own VTEX credentials.

The app is designed for two distinct moments:

• The technical team, agency, or store owner contracts the app in Koru Suite, logs in for the first time, connects the credentials of their own VTEX account, and does the initial setup (brand, salespeople, collections, banners).
• The sales team (salespeople) uses the app day to day from their phone: sharing products, tracking their metrics, and taking care of their clients.

Before you start

Recommended owners

The same person can cover several roles in a small store.

Required access

Before you start, make sure you have:

• A Koru Suite user with the store's website activated with the Power Seller app.
• Access to VTEX Admin for the account, with permission to generate your own App Key.
• The public URL Red Clover gave you to access the app (today, https://app.powerseller.com.ar).
• Your VTEX store's public URL (the storefront domain), to configure the connection.

Koru Power Seller does not create a VTEX License Manager role: salespeople are accounts of their own inside the app (stored in the app's own database, not in VTEX), and the only VTEX access the app uses is that of the App Key the admin loads.

Identifiers you'll come across

How it's contracted and accessed

Unlike the rest of Koru's apps, Power Seller is not installed with the VTEX CLI and does not live inside VTEX Admin: it is a separate application, with its own URL, hosted on Cloudflare Pages. Onboarding a new store touches three different places.

Update and uninstall

Since Power Seller isn't installed on your VTEX account or workspace, there is no vtex install/vtex uninstall command your team runs: the code is deployed centrally by Red Clover and the same build serves every store (there is no per-store version to update).

• Updates: require no action on your part. If a change affects your configuration in some way, Red Clover will let you know separately.
• Cancelling the subscription: deactivating the app for your website in Koru Suite cuts access (see "License and security" below): both salesperson and admin logins get blocked once the license is inactive, with up to ~5 minutes of grace from the validation cache.

Activation and first access

How admins log in (via Koru Suite)

The admin has no password of their own in Power Seller: they sign in with their Koru Suite user, using the app's two-step login (see below). The first time Koru validates that login, Power Seller shows them the Koru websites associated with that person:

• If they have exactly one website and it's already claimed, they go straight to the admin panel.
• If they have zero, several, or a mix of claimed/unclaimed websites, they land on a selector ("Pick a store") with an Enter button (for already-claimed ones) or Configure (to claim a new one) per website.

How salespeople log in

Salespeople have no Koru user: the admin creates them (individually or via CSV) with an email and a temporary password, which they receive by email (if email sending is configured; see below). On first login, the app forces them to change it before continuing.

Two-step login

Every role logs in through the same form, in two steps:

Recommended setup

After connecting VTEX (see above), follow this order before inviting your sales team:

Full configuration

All configuration lives outside VTEX: in Power Seller's own database (Cloudflare D1/KV), scoped per store.

VTEX connection (Admin → Connection)

Roles the App Key needs: Catalog (read) · OMS (view orders) · Master Data v2 (read). The app validates all three before saving; if any fails, it tells you which one (Catalog, OMS, or Master Data).

Brand / White Label (Admin → Brand)

Hot Items / New Arrivals (Admin → Hot Items / New Arrivals)

Salespeople (Admin → Salespeople)

Individual sign-up or CSV import (columns: nombre, nro_vendedor, email, telefono, empresa, sucursal, otros, otros1). Required fields: name, salesperson number, email, company, branch, and password (CSV sign-up generates a temporary password automatically). Email and salesperson number must be unique per store; duplicates are skipped during import without blocking the rest of the batch.

Social Selling banners (Admin → Banners)

If a format isn't loaded, the corresponding download button appears disabled in the salesperson's modal ("the admin hasn't configured this banner yet").

Content calendar (Admin → Calendar)

Each post has a date/time, suggested copy (max. 500 characters), images (story, post, thumbnail), and, optionally, a linked product (looked up by name). The salesperson sees posts grouped by week in their New Arrivals tab.

How each module works

Attributing sales to the salesperson

Each salesperson has their own salesperson number. When they share a product, the generated link adds utm_campaign=<salesperson number> to VTEX's add-to-cart link. On the dashboard side, the app queries OMS filtering by that same value, but using the parameter OMS actually requires (f_UtmCampaign; OMS ignores utm_campaign as a search filter, even though it does accept it as a URL parameter for checkout). Every sales metric (own dashboard, ranking, admin's consolidated dashboard) is scoped to the current calendar month; there is no date-range selector.

Trackable links (shortlinks)

Tapping Share on a product generates a short code (stored in Cloudflare KV, 90-day TTL) that redirects (/r/{code}, 302) to VTEX's real add-to-cart link with the attribution UTMs. Each click is counted in a non-blocking way. If shortlink generation fails for any reason, the modal falls back to showing the product's plain link (without tracking) instead of blocking the share.

CRM and client data

The search (by name, ID document, or email, minimum 2 characters) queries VTEX Master Data's CL entity and always returns masked data: the real value never leaves the edge toward the salesperson's browser. Examples: marcos.garcia@gmail.com → ma***@gmail.com; Marcos García → Marcos G...; document 33456789 → 33.***.**9. A client's detail (purchases, abandoned cart) is requested with the CL document's id, never with the email. If a client has a detected abandoned cart, the app builds a WhatsApp link (wa.me) with a suggested message; it does not use the WhatsApp Business API. The purchase history only shows the client's last 3 invoiced orders, not their full history.

Salesperson catalog

Only products with available stock greater than zero are shown, up to a maximum of 20 products per section (All/Hot Items/New Arrivals), cached for 5 minutes. A discounted product (list price higher than the final price) shows a discount percentage computed by the app itself, not a native VTEX field.

Ranking and dashboard

The ranking is computed per branch (the salesperson's branch field); if a salesperson has no branch loaded, they're compared against a global pool of up to 60 active salespeople. The salesperson's dashboard shows the podium (top 3) and, if the salesperson isn't in it, adds their own row separately with "···" in between. The admin's consolidated dashboard shows the whole team sorted by sales, with average conversion (orders ÷ clicks), and exports to CSV.

Screens and day-to-day operation

License and security

License validation

Every login and every authenticated request validates the website's Koru license (GET /api/auth/widget?website_id&app_id), with these rules:

• Result cached for 5 minutes (fresh) and up to 1 hour as a fallback value.
• Fail-open on transient errors: if Koru doesn't respond or the network fails, the app lets the request through instead of blocking it, so a Koru blip doesn't take down the merchant's operation.
• A license that's explicitly inactive (authorized: false) blocks login with 403 LICENSE_INACTIVE, with up to ~5 minutes of grace from the cache.
• With a session already open, a license cutoff today shows up as "session expired" (401), not as an explicit license message — the real reason only appears once you retry the login. This is a known pending improvement from the development team, not a bug to report.

VTEX credentials

• The admin loads their own App Key/Token from Admin → Connection; they're never requested through any other channel.
• They're validated against 3 private VTEX endpoints (Catalog, OMS, Master Data) before being saved: if the probe fails, nothing is persisted.
• They're encrypted with AES-256-GCM envelope encryption (master key = a project secret) before being saved in the app's database. They're never stored or shown in plain text.
• They're write-only: the panel never shows the saved value again, not even partially. To rotate them, you overwrite them with a new value.

Client data (CRM)

All CRM PII (name, email, phone, document) is masked server-side before responding to the browser: the salesperson never receives the real value, only its masked version. The CRM screen also shows a fixed banner reminding that this is confidential data for exclusive use in sales management.

Passwords and session

• Salesperson passwords are stored with PBKDF2-SHA256 (100,000 iterations), never in plain text.
• The session is a custom JWT (HS256, valid for 8 hours), sent as a Bearer token and stored in the salesperson's/admin's browser.
• The Koru admin has no password of their own in the app: their identity is validated against Koru Suite on every login, not against a stored password here.

Troubleshooting

I can't log in / "Incorrect email or password"

1. If you're a salesperson, confirm with your admin that your account is active (a deactivated salesperson can't log in, even with the correct password).
2. If you're an admin, confirm you're using your Koru Suite user, not a password you've used on another store.
3. An email that belongs to a salesperson at several stores may require picking the store in step 1 of the login.

"This store's license is not active"

1. Confirm in Koru Suite that the Power Seller app is still active for your website.
2. Wait a few minutes: the check is cached for up to 1 hour, so a recent reactivation may take a while to be reflected.
3. If it persists, tell support the email you used and the store's name (without sending passwords).

"This store is still being set up" (salesperson)

Your store was claimed but the admin hasn't loaded (or validated) the VTEX connection in Admin → Connection yet. No salesperson can log in until the admin completes that step and the store moves to active status.

The VTEX connection won't save / "VTEX rejected the credentials"

Check, in this order:

1. That the VTEX account is the real accountName (no https://, no spaces).
2. That the store URL is absolute and uses https://.
3. That the App Key has exactly the three roles: Catalog (read), OMS (view orders), Master Data v2 (read).
4. The error detail shows the result per resource (Catalog/OMS/Master Data): whichever one doesn't say "OK" is the missing role.

The catalog, dashboard, or CRM return a connection error

It's the same error (VTEX_NOT_CONFIGURED) for all three: it means your store doesn't have a valid saved VTEX connection yet. Ask the admin to complete it in Admin → Connection.

No products show up in Hot Items / New Arrivals

1. Confirm the collection ID is correct (use Verify on the configuration screen itself before saving).
2. Confirm you're within the configured validity window (from/to); outside that range, the section deliberately shows an empty state.
3. Remember only products with stock greater than zero are shown: a collection whose products are out of stock may appear empty.

The salesperson didn't receive the welcome or recovery email

Sending emails is best-effort: if the provider (Resend) isn't configured for your store, sending is skipped without breaking sign-up or the reset. On a CSV sign-up, the temporary password is still shown on screen to the admin as a fallback — pass it along manually if the email didn't arrive. For a reset, there's no visible fallback: you need to retry "Forgot my password" once the provider is configured.

"Sign in with VTEX ID" doesn't work

That button is disabled on purpose: it's a planned feature, not implemented yet. Use the normal email-and-password login.

The "Automate across my statuses" toggle doesn't do anything

It's a feature planned for a future phase, visible in the UI but not yet functional. It's not a bug.

Functional limits

The current version:

• Is not a VTEX Admin App: it lives outside VTEX Admin, on its own URL shared by every store that contracts it.
• Has no field to manually paste the Koru Website ID: the store is identified automatically when logging in with a Koru Suite user.
• Only supports one VTEX account per store (one tenant = one row with a single set of VTEX credentials).
• The salesperson's catalog shows a maximum of 20 products per section, and only products with available stock.
• Sales metrics and the ranking are scoped to the current calendar month; there is no date-range selector.
• The CRM's purchase history shows only a client's last 3 invoiced orders.
• Images (logo, banners, calendar) are uploaded to Cloudflare KV with a maximum of 5 MB per file (PNG, JPG, WEBP, GIF, or SVG).
• Shortlinks have a 90-day TTL; past that, the link stops resolving.
• There is no full data purge or bulk export from the UI.
• The "Sign in with VTEX ID" button and the "Automate across my statuses" toggle are visible but disabled: they're planned features, not available yet.
• The single-host, self-service multi-tenant model (two-step login + store selector) is recent: as of this guide, it had only been validated end-to-end with an internal test store, not with a real production client.
• It does not manage VTEX License Manager users nor replace VTEX Admin's native roles: salespeople are accounts of their own inside the app.

Checklist before going live

• Website activated with the Power Seller app in Koru Suite, with the admin associated.
• Store "claimed" from the Power Seller selector (Admin → Connection reachable).
• VTEX App Key generated with the Catalog (read), OMS (view orders), and Master Data v2 (read) roles.
• VTEX connection verified and saved (status "Active connection").
• Brand (name, color, logo) configured.
• At least one test salesperson loaded and tested end to end.
• Hot Items / New Arrivals configured and verified (or deliberately left empty).
• Social Selling banners uploaded.
• Email provider (Resend) configured, or the team knows it must communicate temporary passwords by hand.
• Sales team aware that "Sign in with VTEX ID" and "Automate across my statuses" are not available yet.
• An owner defined to periodically audit the consolidated dashboard.