Koru Recovery

Detects payment-pending VTEX orders, groups related attempts, and organizes manual recovery with full traceability.

Koru Recovery is a VTEX Admin App for teams that recover purchases whose payment was left pending. It queries VTEX OMS, applies store-specific rules, groups related attempts, and creates operational cases so the team can contact customers manually.

The app serves two distinct stages:

• The technical team or VTEX agency installs the app, connects the license, and completes the initial setup.
• The ecommerce or operations team reviews cases, copies the message, contacts the customer through an external channel, and tracks the outcome in VTEX.

Before you begin

Recommended owners

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

Required access

Before installing, make sure you have:

• A valid VTEX Admin session in the store account.
• The official VTEX CLI installed and up to date.
• Permission to install apps in the selected workspace.
• Permission to modify the app settings. Without it, saving returns a permission error and a VTEX account administrator must intervene.
• The ecommerce Website ID from Koru Suite, with Koru Recovery active for that website.
• The bank-transfer details the store wants to include in the message.
• Operational access to OMS to inspect orders and reflect payments through the store's usual process.

Koru Recovery does not create a custom VTEX role. App visibility and human access must be managed with VTEX's existing access controls.

Identifiers you will encounter

Installation with the VTEX CLI

Installation uses the official VTEX CLI. It does not require Store Theme changes or block declarations.

Install in a validation workspace first

If the store has a QA process, install and configure the app in a development workspace first. Replace values in braces:

vtex login {store-account}

vtex use {store-account}/{workspace}

vtex whoami

vtex install {account}.koru-recovery@0.x

vtex list

Open the app in VTEX Admin

Open Koru Recovery from the store setup section in VTEX Admin, or navigate directly to:

https://{workspace}--{store-account}.myvtex.com/admin/koru-recovery

For master, use the account's main Admin domain:

https://{store-account}.myvtex.com/admin/koru-recovery

If the app does not appear in the navigation, confirm vtex list, reload VTEX Admin, and verify that you are viewing the same account and workspace where it was installed.

Install in master

After validating the setup in the appropriate workspace, select master, confirm the context again, and repeat the installation:

vtex use {store-account}/master
vtex whoami
vtex install {account}.koru-recovery@0.x
vtex list

Settings belong to each installation/workspace. Verify the Website ID and operational configuration in the final environment even if you tested them elsewhere.

Updating and uninstalling

Update within the current major

Select the correct account/workspace, confirm it, and install the range again:

vtex whoami
vtex install {account}.koru-recovery@0.x
vtex list

After updating, open the app and verify the license, settings, latest synchronization, and automation status. A code update does not replace operational validation.

Uninstall

Uninstallation applies to the current workspace:

vtex whoami
vtex uninstall {account}.koru-recovery
vtex list

Activation and first access

Get the Website ID

Before first use, Red Clover must activate Koru Recovery for the corresponding website in Koru Suite. The Website ID is available in Koru Suite or is provided during activation.

The Website ID:

• Identifies the ecommerce website in Koru Suite.
• Is not a password or secret.
• Must belong to the same store where the VTEX app is installed.
• Is the only Koru identifier the merchant enters manually.

Connect the store

On first access, the app displays Connect this store to Koru Suite:

The app does not request a separate Koru login. The user is already authenticated in VTEX Admin; Koru Suite only checks that the Website ID + Koru Recovery combination has an active license.

Recommended initial setup

After connecting the license, follow this order so you do not create cases that cannot be contacted yet:

Complete configuration reference

The Settings tab saves per-store rules in VTEX app settings. Unsaved changes do not affect detection or messages.

General

The locale must use a two- or three-letter language code and, optionally, a two-letter region or numeric region code. When empty, the app uses a locale available in the environment.

Operational rules

High tolerances produce more matches: they may group different purchases or flag more possible repurchases. Start with the defaults and adjust using real cases.

Automatic updates

VTEX Scheduler sends a technical heartbeat every 15 minutes. The backend compares the latest attempt/success with syncIntervalMinutes and decides whether a sync is due. Therefore, a 60-minute frequency does not create a separate 60-minute cron.

The range queried by each update is:

now - (expireAfterHours + syncLookbackMarginHours)  →  now

Update now bypasses the functional wait, uses the same idempotent engine, and also attempts to repair the scheduler registration.

Bank-transfer details

The list is stored under the paymentFields key. Each row contains:

Add suggested fields creates Account holder, CUIT/RUT, Alias, and CBU/CVU. These are labels only: you must enter the store's actual values.

Do not enter banking credentials, passwords, tokens, or information that should not be sent to the customer. These fields are intended for public transfer instructions.

Eligible payment methods

The selection is stored under eligiblePaymentMethods. The app discovers methods present in queried orders. Before the first synchronization, the list may be empty.

For each method, the app shows:

• Its display name reported by OMS.
• The normalized key used by the engine.
• A marker when it matches the recommended default.
• A selector to include or exclude it from recovery.

Methods enabled by default through normalized equivalence:

• Credit card.
• Debit card.
• Wallet or digital wallet.
• Instant payment and Pix.

Methods disabled by default:

• Boleto or bank invoice.
• A bank transfer already selected by the customer.
• Cash, cash on delivery, or contraentrega.
• Promissory or manual.
• Gift card, voucher, points, or store credit.
• Offline, custom, or unknown methods.

Comparison ignores capitalization, accents, and separators. It uses both the payment method name and group reported by OMS.

Customer message

The text is stored under messageTemplate. The default English template is:

Hi {{customer.firstName}}, we noticed that your order {{order.id}} for {{order.amount}} is still pending payment.
 
To complete it, you can transfer using these details:
{{payment.fields}}
 
After making the transfer, let us know so we can continue preparing your order.
{{store.name}}

The template supports simple variables. It does not execute Handlebars, conditionals, or arbitrary code.

An unknown variable or one without a value is replaced with an empty string and reported as missing. While any variable is missing, the UI blocks copying and marking the message.

How cases are created

Order source

Koru Recovery queries VTEX OMS for:

payment-pending

The VTEX Incomplete visual filter is not equivalent. An incomplete order without the payment-pending status is not part of recovery.

For every candidate, the backend retrieves the order detail when available and extracts:

• Order ID and order group.
• Transaction IDs.
• OMS status.
• Creation date.
• Customer document, email, phone, ID, and name.
• Amount and currency.
• Payment method name and group.

Eligibility

An order becomes an actionable candidate only when:

1. It is within the queried historical range.
2. OMS reports it as payment-pending.
3. It has reached minOrderAgeMinutes.
4. It has at least one eligible payment method.
5. A customer identity or, as fallback, an orderGroup can be resolved.
6. There is no exact paid repurchase that closes the case.

Orders that are too recent and non-eligible methods are counted in the technical sync result but do not create actionable cases.

Koru Recovery is gateway-independent. It does not process or store card credentials and does not call payment gateways. Any configured eligible method follows the same recovery flow once VTEX OMS exposes the order as payment-pending.

Identity and grouping

Identity is resolved in this order:

1. Document.
2. Email.
3. Phone.
4. Customer ID.
5. orderGroup, only as a grouping fallback.

Attempts are grouped when they share the same identity and currency, have an amount within tolerance, and occur within the configured rolling window measured from the first attempt in the group. The window does not use fixed clock buckets and later attempts do not extend it transitively.

The case retains all related orders, transaction IDs, and order groups. The primary order is the most recent order in the group.

Amounts and currencies

OMS amounts are normalized as minor units before comparison. Currency is resolved in this order:

1. OMS currencyCode.
2. Order preferences.
3. A fallback available in the execution context.

Orders in different currencies are never grouped or compared as repurchases. The app supports valid currency codes supplied by VTEX OMS and formats each amount in its own currency, without exchange-rate conversion. If amount and currency cannot be resolved reliably, it does not generate an ambiguous message.

Exact and possible repurchases

Duplicate-contact prevention has two levels:

For a possible repurchase, open the related orders in OMS and verify that the customer did not complete another purchase. If recovery should continue, use Continue anyway. The confirmation is audited and does not erase the historical flag.

Statuses and lifecycle

Case statuses

The internal status values remain in Spanish because they are persisted domain identifiers. The UI translates their visible labels.

Automatic transitions

• A synchronization creates or updates pendiente cases.
• If a related order reaches a paid OMS stage, an open case moves to cerrada-pagada.
• If all grouped orders are canceled, an open case moves to descartada with the oms-cancelled reason.
• If only one grouped order is canceled while another remains open, the case is not discarded automatically.
• When the expiration timestamp is reached, an open case moves to expirada.

OMS stages interpreted as paid:

window-to-cancel
payment-approved
ready-for-handling
authorize-fulfillment
release-to-fulfillment
handling
waiting-for-fulfillment
ready-for-invoicing
invoice
invoiced

Manual transitions

• pendiente → mensaje-enviado: Mark sent.
• pendiente or mensaje-enviado → descartada: Discard case.
• A recheck can close a case as paid when OMS already reflects payment.
• A note or message copy does not change status.
• A discarded case does not automatically reopen as pending.

Day-to-day operation

Recommended workflow

Metrics

The summary counts cases, not orders:

• Pending.
• Messages sent.
• Closed paid.
• Discarded.
• Expired.
• Open, unconfirmed possible repurchases.

A case containing several grouped orders counts as one.

Search and filters

You can filter by status and possible repurchases. Search indexes:

• Case ID.
• Primary and related orders.
• Transaction IDs.
• Customer document, email, phone, and ID.
• First and last name.

The list supports 10, 20, 50, or 100 cases per page. Cases are sorted by last update, most recent first.

Search is case- and accent-insensitive and matches normalized complete identifiers, complete indexed values, individual name words, or their numeric-only form. It is not fuzzy or arbitrary substring search.

Export cases

Export creates koru-recovery-cases.csv with every case that matches the current status, possible-repurchase, and search filters—not only the visible page. The app retrieves all result pages, displays the number of cases fetched while the export is running, and includes these columns:

• Customer.
• Primary order.
• Status.
• Payment method.
• Amount.
• Update date.

The selected page size does not limit the export.

Case detail

The detail view shows:

• Case ID and status.
• Customer, email, document, and phone.
• Amount and currency.
• Primary order with a direct VTEX link.
• Last observed VTEX status.
• Primary Transaction ID with a direct link.
• Payment method.
• Last update and expiration.
• Message preview.
• Related orders, transaction IDs, and order groups.
• Discard reason when present.
• Internal notes.
• Audit trail.

Available actions

Audit trail

The audit trail separates manual (admin) from automatic (system) actions. It stores timestamp, actor, action, previous/next status, orders, transactions, note/reason, and technical metadata when applicable.

It includes, among other events:

• Detection, update, eligibility, and grouping.
• Exact or possible repurchase.
• Confirmation to continue.
• Message copy and mark sent.
• Recheck.
• Notes and discards.
• Closing on payment, OMS cancellation, and expiration.
• Names of changed configuration fields, without storing their sensitive values in the event.

Export within Audit retrieves every audit event for the case, not only the events initially displayed. The CSV contains Event ID, ISO timestamp, localized timestamp, visible action, action code, actor type, actor, previous status, next status, Case ID, orders, transaction IDs, note, and metadata. Progress shows the number of events retrieved.

Synchronization and automation

What each update does

A run:

1. Acquires a lock to prevent concurrent synchronizations.
2. Queries every OMS page in the configured range.
3. Retrieves candidate order details.
4. Records discovered payment methods.
5. Applies age and eligibility.
6. Groups attempts.
7. Searches for exact and heuristic repurchases.
8. Creates or updates cases idempotently.
9. Rechecks payments and cancellations for open cases.
10. Expires cases whose time limit has been reached.
11. Rebuilds metrics and saves the run state.

If another run owns an active lock, the result is Locked by another run, without duplicating work.

Automation status

If OMS fails, the app records the error and preserves existing cases. It does not delete data because of a partial or failed synchronization.

License and security

License validation

Every operational route requires:

1. A valid VTEX Admin session.
2. An active Koru license for the Website ID and Koru Recovery App ID.

The app-settings route stays outside the license gate to allow bootstrap, but still requires a valid admin session.

To tolerate transient failures:

• A positive authorization is cached briefly in memory.
• If Koru Suite fails because of network or server errors, a persisted positive validation may preserve access for up to 72 hours.
• An explicit revocation blocks business operations after a short protection against transient negative responses expires.

These periods are internal and cannot be configured per store.

Data and credentials

• React only calls Koru Recovery's private routes.
• The backend uses the VTEX IO context and policies for OMS.
• The app does not request or store merchant AppKey/AppToken credentials.
• No Koru secrets are exposed in the browser.
• Website ID and App ID identify resources but are not passwords.
• Cases, indexes, audit events, metrics, and sync state are persisted in VBase under the functional koru-recovery bucket.
• Cases contain operational snapshots of customer and order data. Apply the store's access and privacy policies to VTEX Admin users.

Troubleshooting

The app does not appear after installation

1. Run vtex whoami.
2. Confirm the account and workspace.
3. Run vtex list and find {account}.koru-recovery.
4. Reload VTEX Admin.
5. Try the direct /admin/koru-recovery URL on the same domain/workspace.

The session was rejected or expired

Sign in to VTEX Admin again and reload the app. Private routes return 401 when a valid admin session is missing.

I cannot save settings

• Confirm that your user can modify app settings.
• Check for numeric fields outside their ranges.
• Verify that Website ID and template are not empty.
• Use a valid locale such as en-US.
• Complete or remove enabled transfer rows with a missing label or value.

A permission error requires a VTEX administrator. Retrying with the same user does not change that authorization.

The license is inactive

1. Compare the Website ID with the correct website in Koru Suite.
2. Confirm that Koru Recovery is active for that website.
3. Check for copied whitespace.
4. Retry validation.
5. If it persists, provide the Website ID, account, and workspace to support without sending credentials.

The license could not be verified

We could not verify the license is a transient availability state, not proof that the license was revoked. Retry after a few seconds. Only Koru license is not active indicates an explicitly inactive or unconfigured license.

“Update now” does not create cases

Review, in this order:

1. Whether OMS contains orders with the actual payment-pending status.
2. Whether they are inside the configured historical range.
3. Whether they reached the minimum age.
4. Whether their payment method is enabled.
5. Whether OMS detail contains enough customer, amount, and currency data.
6. Whether an exact paid repurchase exists.

An order shown as Incomplete without payment-pending is not a candidate.

No payment methods appear

Methods are discovered during a synchronization over payment-pending orders. Run Update now when at least one test order exists inside the range. An unknown method is disabled by default.

Copy message or Mark sent is disabled

Check:

• At least one complete and enabled transfer detail.
• No missing variables in the preview.
• pendiente status for Mark sent.
• An actionable status for copying.
• Confirmation of a possible repurchase.

The preview warning identifies the variable that could not be resolved.

The case did not close after payment

1. Open the order from the case detail.
2. Confirm OMS displays a stage interpreted as paid.
3. Run Recheck for that case or Update now for all cases.
4. If OMS still shows payment-pending, complete the store's VTEX payment process first.

Marking a message as sent does not mark the order as paid.

Automatic updates are delayed

• Compare the last automatic check with syncIntervalMinutes.
• A “Waiting” status is normal when the heartbeat is not due yet.
• Run Update now: besides syncing, it attempts to repair the schedule.
• If an error appears, record its time, account, workspace, and message.

For technical support in production:

vtex logs {account}.koru-recovery

Do not share tokens, cookies, private banking details, or unnecessary personal data.

Functional limits

The current version:

• Only works with OMS payment-pending orders.
• Uses manual contact; it does not automate channels.
• Offers offline bank transfer; it does not process payments.
• Does not create or reactivate payment links/transactions.
• Does not change OMS statuses by itself.
• Does not convert currencies.
• Does not create human VTEX roles.
• Does not use Master Data for cases.
• Does not automatically reopen discarded cases.

Go-live checklist

• Koru Recovery is installed in the correct account and workspace.
• The store Website ID was verified.
• The active-license indicator is visible.
• Store name and language/region were reviewed.
• Ecommerce approved the operational rules.
• Frequency and historical range match the store volume.
• At least one complete and enabled transfer detail exists.
• Eligible methods were reviewed after a synchronization.
• The template has no missing variables.
• A test case was compared with OMS.
• Operators know that copy/send does not confirm payment.
• An owner is assigned to reflect transfers in VTEX.
• Discard, notes, and possible-repurchase workflows are agreed.
• The latest manual synchronization completed without errors.