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.

Permissions the app requests

When you install it, VTEX asks you to accept these permissions:

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 {vendor}.pickup-cleaner@2.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 {vendor}.pickup-cleaner@2.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 {vendor}.pickup-cleaner@2.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 {vendor}.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. The Koru App ID is built into the app and is not configured.

Connect the store

On first access, the app displays Connect this store with 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. The app validates every value before saving it and validates it again when reading it: if a saved value is invalid (for example, a time that is not HH:MM), the app shows the The app configuration has an invalid value screen until it is fixed in Admin → Apps → Pickup Cleaner.

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 and the maximum is 50 km.

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 deletion and Run now delete up to 400 points per run. In scheduled deletion, if more candidates remain, the following checks within the same hour continue (up to about 1,600 per hour). The history says so.

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. Each tab includes a guided tour that opens the first time you visit it and that you can replay with the View tour button. The interface is available in Spanish, English, and Portuguese, following the VTEX Admin language.

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

When the app is installed or updated, it registers a task in VTEX Scheduler that checks in with the app every 15 minutes. That check does not delete anything on its own: on each one, the app decides whether it should act.

Sequence of each check:

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. If that hour was already completed, does nothing. This keeps the deletion from repeating within the same hour.
5. Validates the Koru license. If the license is inactive, or Koru does not respond and there is no recent positive validation, the check is blocked: it deletes nothing and does not mark the hour, so if the issue is resolved within that hour, the next check runs it.
6. Classifies candidates using the same tag/geo criteria described above and deletes up to 400.
7. If no candidates remain, marks the hour as completed. If some remain, the next check within the same hour continues.
8. Records the result in the history and in the automation status.

Two checks never run at the same time: if one is still deleting when the next arrives, the second one waits its turn.

Run now

The Run now button runs the same deletion without waiting for the schedule, using the saved configuration:

• It does not depend on the toggle, the hour, or whether the hour was already completed.
• If the form has unsaved changes, the button stays disabled until you save them, so what you see on screen is what runs.
• Before running, it asks for confirmation, shows the filters it will apply, and offers to download a JSON backup of the candidate points.
• It deletes up to 400 points per run.

Repair schedule

If scheduled deletion stopped running (for example, the status shows no recent checks), Repair schedule registers the task in VTEX Scheduler again. It does not delete anything.

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 run leaves candidates unprocessed because of the 400 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.

The license is always validated from the app's server, never from the browser. To tolerate transient failures:

• A positive validation is reused for a few minutes.
• If Koru Suite does not respond, the app keeps working with the last positive validation from the past 72 hours. Without one, it shows The license cannot be verified right now and automation is blocked: this is not a license problem, and retrying later is enough.
• If Koru Suite reports the license as inactive, the app stops operating within a few minutes and shows the inactive-license screen. A reactivation takes effect in about a minute.

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 {vendor}.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 and at most 50 km.

The app shows "The app configuration has an invalid value"

A value saved in the app settings is not valid (a time that is not HH:MM, a timezone that does not exist, or a radius out of range). Fix it in Admin → Apps → Pickup Cleaner and retry.

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.

The app shows "The license cannot be verified right now"

Koru Suite did not respond and there is no positive validation from the past 72 hours. This is not a license problem: retry in a few minutes. While it lasts, automation is blocked and deletes nothing.

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 automation status (at the top of the Automation tab): it shows the result of the last check and its reason, for example that it was not the configured hour, that the hour was already completed, or that the license was blocked.
7. If the status shows no recent checks, use Repair schedule.

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.
• Deletes up to 400 points per run. Scheduled deletion continues in the following checks within the same hour (up to about 1,600 per hour).
• Uses exact, case-sensitive tag matching, with no tolerance for typos made outside the app.
• Accepts a geographic radius of up to 50 km in automation; the Geo cleanup tab 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.
• The automation status was reviewed after the first scheduled hour.
• An owner is assigned to periodically review the operation history.