Koru Pickup Cleaner

Detects and bulk-deletes third-party pickup points cluttering your VTEX pickup catalog, while always preserving your own store branches.

Koru Pickup Cleaner is a VTEX Admin App that identifies and bulk-deletes third-party logistics pickup points (Andreani, OCA, Correo Argentino, etc.) that end up mixed into the store's pickup point catalog, without ever touching the store's own branches.

Many logistics integrations automatically create hundreds or thousands of pickup points for their own agencies, available at checkout. This clutters the pickup point catalog, especially when those points sit very close to the store's real branches or duplicate their coverage.

The app serves two distinct stages:

• The technical team or VTEX agency installs the app, connects the license, and defines the tag that identifies the store's own branches.
• The ecommerce or logistics team reviews candidates, adjusts filters and the search radius, and decides what to clean up manually or through automation.

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.
• A License Manager role with access to the Logistics module. Without this access, the Logistics API returns 401/403 when listing, editing, or deleting points.
• The official VTEX CLI installed and up to date.
• Permission to install apps in the selected workspace and to modify the app settings.
• The ecommerce Website ID from Koru Suite, with Koru Pickup Cleaner active for that site.
• The exact tag (case-sensitive) that identifies your own branches in the pickup point catalog.

Koru Pickup Cleaner does not create a custom VTEX role. Access to Logistics is managed through VTEX License Manager's existing access controls.

Identifiers you will encounter

Installation with the VTEX CLI

Installation uses the official VTEX CLI. It is a standalone Admin App: it does not require Store Theme changes or storefront 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}.pickup-cleaner@1.x

vtex list

Open the app in VTEX Admin

Open Pickup Cleaner from the store setup section in VTEX Admin (sidebar menu), or navigate directly to:

https://{workspace}--{store-account}.myvtex.com/admin/pickup-cleaner

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

https://{store-account}.myvtex.com/admin/pickup-cleaner

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}.pickup-cleaner@1.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}.pickup-cleaner@1.x
vtex list

After updating, open the app and verify the license, own-branch tag, automation settings, and the latest entry in the operation history. A code update does not replace operational validation.

Uninstall

Uninstallation applies to the current workspace:

vtex whoami
vtex uninstall {account}.pickup-cleaner
vtex list

Activation and first access

Get the Website ID

Before first use, Red Clover must activate Koru Pickup Cleaner 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. There is also an optional Koru App ID field intended as an advanced escape hatch; in most cases it does not need to be touched.

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 Pickup Cleaner combination has an active license.

Recommended initial setup

Follow this order to avoid accidentally deleting points that are actually your own branches:

Complete configuration reference

All configuration lives in VTEX app settings (Admin → Apps → Pickup Cleaner, or from the app's own Automation tab). There is no other configuration channel.

General and license

Automation (scheduled deletion)

How it identifies what to clean up

Tag-based classification

Third-party logistics providers (Andreani, OCA, Correo Argentino, etc.) do not mark VTEX's native isThirdPartyPickup field when creating their pickup points. Because of this, Koru Pickup Cleaner cannot rely on that field and instead uses a tag-based heuristic:

1. A point carrying the tag configured in ownBranchTag is never considered a deletion candidate, with no exceptions and regardless of other filters.
2. If scheduledTags are configured, the point must carry at least one of those tags to qualify. If the list is empty, any point without the own-branch tag qualifies.
3. If scheduledOnlyInactive is enabled, the point must additionally have isActive: false.

Geographic radius cleanup (optional)

When scheduledGeoEnabled is on, an additional filter is applied on top of the tag-filtered candidates: only points within the configured radius (scheduledGeoRadiusKm) of some own branch remain as final candidates, computed with the Haversine distance formula over latitude and longitude.

Guardrails of the geographic mode:

• Coordinates must be numeric and within range (latitude -90 to 90, longitude -180 to 180). The pair (0, 0) is treated as empty data, not a real location.
• If no own branch has valid coordinates, nothing is deleted.
• A candidate without valid coordinates is also not deleted in geographic mode: it is excluded for safety, not included by default.
• The default radius is 1.5 km. If the saved value is not a finite positive number, the app falls back to that default.

Cleanup action: permanent deletion

The only cleanup action is a physical DELETE against the VTEX Logistics API. It is irreversible from VTEX: the only way to "undo" a deletion is to manually recreate the point from a previously exported CSV/JSON backup.

To avoid overloading the API, deletions run in batches:

• Batches of 15 parallel requests, with a short pause between batches.
• Scheduled cleanup has a cap of 2,000 deletions per run. If there are more candidates, the rest are left for the next run where the configured condition is met (this is stated explicitly in the operation history).

Other available actions

Koru Pickup Cleaner does more than delete pickup points:

• Edit an individual point: updates the full record in Logistics (VTEX's API does not support partial updates).
• Add tags in bulk: adds new tags without replacing existing ones on the current selection.
• Bulk import or update from CSV or Excel.
• Export CSV of the current filtered list, useful as a manual, re-importable backup.

Screens and day-to-day operation

The app is organized into four tabs within a single panel.

CSV or Excel import

Required columns: id, name, latitude, longitude, postalCode, country, city, state, street, number.

Optional columns: description, instructions, neighborhood, complement, reference, isActive, tagsLabel, seller, and per-day business hours (openMon/closeMon … openSun/closeSun).

Invalid rows are shown in the preview with the exact error, but they do not block the import of the remaining valid rows.

Automation and scheduled execution

Automatic cleanup runs on a technical heartbeat that VTEX Scheduler triggers every hour on the hour. That heartbeat does not automatically run a deletion: the app decides internally, on every run, whether it should act.

Sequence of each run:

1. Reads the current settings.
2. If Automatic deletion enabled is off, does nothing.
3. If the current time (in the configured timezone) does not match Deletion time, does nothing.
4. Validates the Koru license. If it is not active, the run is skipped without marking the hour as executed, so a later reactivation runs on the next hourly pass.
5. Checks that this specific hour has not already run (idempotency guard), preventing a duplicate deletion if the heartbeat repeats.
6. Classifies candidates using the same tag/geo criteria described above and executes the deletion, respecting the 2,000-per-run cap.
7. Records the result in the operation history.

The Run now button on the Automation tab triggers the same logic manually, without waiting for the configured time — useful for testing the configuration or forcing a one-off cleanup.

History and audit trail

Every relevant action (manual deletion, import, geographic cleanup, bulk tagging, individual edit, and automation runs) is recorded in an operation history, visible on the Automation tab.

• Stores the latest 100 operations, most recent first.
• Each entry includes the operation type, affected count, a result detail, and, for manual actions, the VTEX user who performed it. Automatic runs are shown as a system action, with no associated user.
• When a scheduled run leaves candidates unprocessed because of the 2,000 cap, the detail states this explicitly.

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 the Koru Pickup Cleaner App ID.

To tolerate transient network or license-service failures, a positive authorization is cached briefly; an explicit revoked-license response blocks use of the app immediately.

Data and credentials

• The browser never calls the VTEX Logistics API directly: every request goes through the app's own routes, which handle authentication with internal VTEX IO tokens.
• The app does not request or store merchant AppKey/AppToken credentials. The identity used to operate Logistics is the logged-in admin's own session (for manual actions) or the app's own token (for scheduled automation).
• Website ID and App ID identify resources but are not passwords.
• The operation history is persisted in the app's internal storage, not in Master Data or VTEX orders.
• Requires the logged-in user to have access to the Logistics module in their License Manager role; without that access, listing, editing, or deleting actions fail.

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}.pickup-cleaner.
4. Reload VTEX Admin.
5. Try the direct /admin/pickup-cleaner URL on the same domain/workspace.

The session was rejected or expired

Sign in to VTEX Admin again and reload the app.

I cannot list, edit, or delete points

Confirm your user has access to the Logistics module in their License Manager role. Without that permission, the Logistics API rejects the operation even if the VTEX Admin session is valid.

I cannot save settings

• Confirm that your user can modify app settings.
• Check that the Website ID is not empty.
• Verify the time format (HH:MM) and that the timezone is one of the available options.
• Check that the geographic radius is a number greater than 0.

The license is inactive

1. Compare the Website ID with the correct website in Koru Suite.
2. Confirm that Koru Pickup Cleaner 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.

Scheduled cleanup deletes nothing

Review, in this order:

1. That Automatic deletion enabled is on.
2. That the current time matches Deletion time, considering the configured timezone.
3. That the own-branch tag is loaded correctly (exact upper/lowercase) on your real branches.
4. That points without that tag exist and satisfy the configured scheduledTags and scheduledOnlyInactive filters.
5. If using geographic mode, that at least one own branch has valid coordinates.
6. The operation history: it may show that the license was not active at that time, or that this specific hour already ran.

Geographic cleanup finds no candidates

• Confirm that own branches have latitude and longitude set (not 0, 0).
• Temporarily increase the search radius to check whether the issue is distance or missing data.
• Verify that candidate points also have valid coordinates.

The import rejects rows

Check the preview: each invalid row shows the exact reason (empty column, out-of-range coordinate, ID with spaces). Fix the file and re-upload; valid rows are unaffected by errors in other rows.

Functional limits

The current version:

• Syncs up to 10,000 pickup points per load (100 pages of 100). Larger catalogs are not fully loaded in a single sync.
• Performs permanent deletions; it does not offer its own recycle bin.
• Caps scheduled deletion at 2,000 deletions per run.
• Has a Spanish-only interface, regardless of the language configured on the VTEX account.
• Uses exact, case-sensitive tag matching, with no tolerance for typos made outside the app.
• Does not enforce a hard cap on the geographic radius beyond requiring a number greater than 0 (the UI recommends not exceeding 3 km).
• Always operates on the VTEX account where it is installed; it does not manage pickup points from another account from a single installation.
• Does not integrate with VTEX OMS or Master Data: it only works against the Logistics API.

Go-live checklist

• Koru Pickup Cleaner is installed in the correct account and workspace.
• The store Website ID was verified.
• The active license was confirmed.
• The user has access to the Logistics module in their License Manager role.
• The catalog was synced and the Own/Third-party stats were reviewed.
• The own-branch tag was verified against the real catalog, including case.
• A CSV backup was exported before the first real deletion.
• A small test deletion was run and validated in the history.
• The geographic radius was tested in analysis mode before enabling it in automation.
• Automation (time, timezone, tags, filters) was configured only after manual validation.
• An owner is assigned to periodically review the operation history.