Koru Catalog Boost

Bulk VTEX catalog management from an Excel/CSV spreadsheet — categories, brands, brand logos and product images, with an auditable history.

Koru Catalog Boost is a VTEX Admin App for bulk creating, deactivating and updating your catalog from an Excel or CSV spreadsheet: categories (with a hierarchy preview), brands, brand logos and product images — including date-scheduled visibility.

The app is designed for two different moments:

• The technical team or VTEX agency installs the app, connects the license, and defines the defaults for new categories.
• The catalog or ecommerce team prepares the spreadsheets, uploads files, reviews the preview before applying, and follows up in the operation history.

Before you start

Recommended owners

A single person can cover several roles in a small store.

Required access

Before installing, confirm you have:

• A valid VTEX Admin session on the store's account.
• A License Manager role with Catalog - Full access. Without this access, the Catalog API responds 401/403 when creating, updating, moving, or deactivating any catalog entity.
• The official VTEX CLI, installed and up to date.
• Permission to install apps on the chosen workspace and to modify the app's settings.
• The ecommerce's Website ID in Koru Suite and Koru Catalog Boost active for that site.
• Category, brand and image spreadsheets ready (you can download each module's template from within the app itself).

Koru Catalog Boost does not create its own VTEX role. Access to the Catalog API is managed with the access controls already available in VTEX License Manager.

Identifiers you'll come across

Installation with the VTEX CLI

Installation uses the official VTEX CLI. It's a native Admin App: it does not require modifying the Store Theme or declaring storefront blocks.

Install first in a validation workspace

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

vtex login {store-account}

vtex use {store-account}/{workspace}

vtex whoami

vtex install {account}.catalogo-boost@1.x

vtex list

Opening the app in VTEX Admin

You can open Catalog Boost from the store's configuration section in VTEX Admin (side menu) or navigate directly:

https://{workspace}--{store-account}.myvtex.com/admin/catalogo-boost

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

https://{store-account}.myvtex.com/admin/catalogo-boost

If the app doesn't show up in navigation, confirm vtex list, reload VTEX Admin, and verify you're looking at the same account and workspace where you installed it.

Installing on master

Once the setup is validated in the corresponding workspace, select master, re-confirm the context, and repeat the installation:

vtex use {store-account}/master
vtex whoami
vtex install {account}.catalogo-boost@1.x
vtex list

Settings are per installation/workspace. Verify the Website ID and category defaults in the final environment even if you already tested them in another workspace.

Update and uninstall

Updating within the current major

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

vtex whoami
vtex install {account}.catalogo-boost@1.x
vtex list

After updating, open the app and verify the license, the category defaults, and that the category tree loads correctly. Don't assume a code update replaces operational validation.

Uninstalling

Uninstalling applies to the current workspace:

vtex whoami
vtex uninstall {account}.catalogo-boost
vtex list

Activation and first access

Getting the Website ID

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

The Website ID:

• Identifies the ecommerce within Koru Suite.
• Is not a password or a secret.
• Must belong to the same VTEX store where you installed the app.
• Is the only Koru identifier the merchant enters manually. There's also an optional Koru App ID field intended as an advanced escape hatch; in the vast majority of cases you won't need to touch it.

Connecting the store

On first access, the app shows Connect this store with Koru Suite:

The app does not ask for an additional Koru login. The person is already authenticated in VTEX Admin; Koru Suite only validates that the Website ID + Koru Catalog Boost combination has an active license.

Recommended setup order

Follow this order before operating with real data:

Full configuration

All configuration lives in VTEX app settings (Admin → Apps → Catalog Boost). There is no other configuration channel.

How each module works

Categories

The module has three modes, selectable with the buttons at the top:

Load / Update. You upload a spreadsheet (columns: Categoria ID (Category ID) · Nombre (Name) · ID Padre (Parent ID) · Title · Description · Keywords · Activa (Active)) and the app validates each row before showing the preview:

• Name is required.
• If a row has a Parent ID, that id must already exist in the VTEX tree or correspond to another row in the same spreadsheet that will also be created.
• A row cannot declare itself as its own parent (circular hierarchy).
• Two rows cannot share the same name under the same parent (duplicate within the same branch).

Rows with errors show the exact reason and are excluded; you can still apply the valid rows. The preview builds the resulting tree by combining the real tree with the new categories from the spreadsheet, so you see the final hierarchy before touching anything in VTEX.

Fields VTEX requires that the spreadsheet doesn't provide are filled with categoryDefaults plus a few code defaults (Title/Keywords fall back to the Name if left empty, Description stays blank). GlobalCategoryId is never sent as 0: if there's no valid value (greater than 0) configured, the field is omitted entirely, because VTEX rejects a 0 with a "Global category not found" error.

Relocate. VTEX does not allow reparenting an existing category: any change to FatherCategoryId — at the same level or to another department — is rejected by the Catalog API with 400 "Cannot move category level". That's why "relocating" doesn't move the original category: you drag a leaf category (with no subcategories) onto its new parent in the tree, and on confirmation the app:

1. Creates a copy of the category under the new parent.
2. (Optional, checked by default) Migrates the products from the source category to the new one, reassigning each product's CategoryId and DepartmentId.
3. Deactivates the original — but only if every product was migrated successfully. If any product couldn't be migrated, the original stays active (to avoid leaving orphaned products hanging off a deactivated category) and the app tells you how many are still pending.

Subcategories are never migrated along with their products; that's why the tree only allows dragging leaf categories in this mode. Moves stay staged in yellow (pending) until you confirm, and you can undo each one before applying.

Deactivate. VTEX does not expose a category DELETE (it discourages deleting categories with associated products). Select one or more categories in the tree via checkbox and confirm: the app deactivates each one (IsActive=false) while preserving the rest of its fields.

All category mutations are processed in batches of 10 requests with a 600 ms pause between batches.

Brands

Brand data sub-tab: you upload a spreadsheet (columns: Brand ID · Nombre (Name) · URL Friendly · Activa (Active) · Titulo SEO (SEO Title) · Descripcion SEO (SEO Description)). It validates:

• Name is required and must be unique, both against existing brands and within the same spreadsheet.
• If a row has a URL Friendly, it must be a valid slug (lowercase letters, numbers, and hyphens). If left empty, the app auto-generates one from the name (accents removed, lowercase, hyphenated).

New brands are activated by default (Active: true), and the SEO Title (SiteTitle) falls back to the name if left empty. Processing runs in batches of 10 with a 600 ms pause.

Logos sub-tab: the brand entity in the Catalog API has no image field, and VTEX offers no REST API to upload the logo. The only native mechanism is the "Images and files" section of VTEX's legacy Admin (the MarcaForm.aspx form, file type LogoMarca), which the app replicates server-side: it downloads that form, resubmits its current fields together with the file, and confirms VTEX accepted it.

Things to keep in mind:

• The binary file does not go through a spreadsheet: it's uploaded by dragging or selecting images in a dedicated dropzone.
• Automatic matching of file → brand tries, in order: a numeric filename = Brand ID → slug/URL Friendly → normalized brand name (only if unique). Files that don't match are flagged "unassigned" and you can assign them manually with a selector; nothing is uploaded until every file in the batch is assigned.
• VTEX only accepts JPG or GIF for the logo (it validates by file extension/type, not by actual content). The app automatically converts any PNG/WebP you upload to JPG, flattening transparency onto a white background before sending it.
• Each logo requires two calls to the legacy form (one read, one write), so they're processed in smaller batches: 4 per batch, with an 800 ms pause between batches, and the browser sends them in chunks of 6 to avoid exceeding the route's time limit.

Images

You upload a spreadsheet (columns: SKU ID · Nombre Imagen (Image Name) · URL Imagen (Image URL) · Orden (Order) · Principal (Main) · Reemplazar (Replace) · Eliminar (Delete) · Fecha Inicio (Start Date) · Fecha Fin (End Date)), grouped internally by SKU. Each row represents one operation:

You can also look up a SKU's current images (with thumbnails) before uploading changes — useful to confirm exact names when replacing or deleting.

Scheduled visibility. The image Catalog API has no start/end dates, so Koru Catalog Boost emulates it: if a row has a Start Date and/or End Date (format YYYY-MM-DD or DD/MM/YYYY, with optional HH:MM time, interpreted in the browser timezone of whoever uploads the file), that operation is not applied instantly: it's queued as one or two scheduled jobs (one to make the image appear on the Start Date, another to make it disappear on the End Date). Rows without dates are applied immediately, as usual.

Scheduled jobs live in a persisted queue, and an hourly cron (runs on the hour, every hour) checks which ones are due and applies them: associate to make the image appear, or a lookup + delete by Name to make it disappear. Each job sits in pending, applied, failed, or cancelled state; a job that's already been processed isn't touched again even if the cron runs again. The Scheduled tab lists the full queue and lets you cancel any job still pending.

Immediate image mutations are processed in batches of 8 (lighter than categories or brands, since each SKU can involve several calls), with a 600 ms pause between batches.

Screens and daily operation

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

History and auditing

Every relevant operation (category load/update, relocation, deactivation, brand creation, logo uploads, image operations, and scheduled-visibility runs by the cron) is logged in the History module.

• Keeps the last 500 operations, most recent first.
• Each entry includes the module (Categories/Brands/Images), operation type, success and error counts, a readable summary of the result, up to 50 affected identifiers, and up to 50 actual errors ({id, error}, not just a count).
• Manual actions log the VTEX user's email who performed them (obtained from the admin's own session token, already validated by authorizeAdmin, with no extra calls). Automatic scheduled-visibility cron runs are logged under the cron user.
• When a relocation leaves products unmigrated, the detail explicitly states that the original category was not deactivated and how many products are still pending.

License and security

License validation

All operational catalog routes require, in this order:

1. A valid VTEX Admin session (authorizeAdmin, checked against License Manager).
2. An active Koru license for the Website ID and Koru Catalog Boost's App ID (authorizeKoruLicense).

The app-settings route (the Koru gate's bootstrap) is excluded from the second check so the initial setup screen can load, but it still requires a valid admin session.

Failure-tolerance policy:

• A license explicitly revoked by Koru Suite blocks usage immediately (402).
• Without a configured koruWebsiteId, the block is also immediate, with a message indicating where to enter it.
• On a network failure or an error from Koru's licensing service, the app does not block usage (a Koru outage shouldn't take down the merchant's operation); that result is not cached, so the next request retries the real check.
• A positive authorization is periodically revalidated in the background; a revocation is retried more frequently, so a reactivation in Koru Suite takes effect quickly.

Data and credentials

• The browser never calls the VTEX Catalog API directly: every request goes through the app's own routes (/_v/private/catalogo-boost/*).
• The identity used to operate the Catalog API is the logged-in admin's own session (the "Catalog - Full access" role in License Manager); the app does not request or store the merchant's AppKey/AppToken.
• The scheduled-visibility cron uses the app's own token, not a human user's.
• Website ID and App ID identify resources, but are not passwords.
• The operation history and the scheduled-visibility queue are persisted in the app's internal storage (VBase), not in Master Data or Orders.
• Uploading a brand logo means the app calls a section of VTEX's legacy Admin on behalf of the logged-in admin; no additional credentials are sent for that.

Troubleshooting

The app doesn't show up after installing

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

The session was rejected or expired

Log back into VTEX Admin and reload the app. Private routes respond 401 when a valid admin session is missing.

I can't create, update, move, or deactivate categories/brands/images

Confirm your user has Catalog - Full access in their License Manager role. Without that permission, the Catalog API rejects the operation even with a valid VTEX Admin session.

"Couldn't move" / "Cannot move category level"

This is a VTEX restriction, not an app error: the Catalog API rejects any change of parent on an existing category. Use the Relocate mode instead of trying to reparent directly: it creates a copy at the destination, migrates products if applicable, and deactivates the original.

"Global category not found" when creating or updating a category

The category involved has an invalid Global Category. Assign it a valid one from VTEX Admin (Catalog → Categories → edit) and retry; the app never intentionally sends a 0 to avoid exactly this error, but an already-invalid value stored in VTEX can still trigger it.

The relocation didn't deactivate the original category

Check the detailed result: if products were left unmigrated, the app deliberately leaves the original active to avoid hiding orphaned products. Retry migrating those specific products, or migrate them manually in VTEX Admin before deactivating the original by hand.

The brand logo won't upload / is rejected

• Confirm the file matched the correct brand before applying (check the "auto"/"manual" indicator in the preview).
• Remember VTEX only accepts JPG or GIF; the app automatically converts other formats, but if the error persists, try a manually exported JPG.
• If the error mentions a backend connection problem with VTEX, retry: it may be a transient issue with the legacy form VTEX uses for this mechanism.

No images show up in a SKU's preview

Verify the SKU ID is numeric and exists in the catalog. A SKU with no associated images shows explicitly "no images", not an error.

A scheduled image didn't appear/disappear on the expected date

1. Check the Scheduled tab: confirm the job's status (pending, applied, failed, cancelled).
2. Remember the cron runs once per hour, on the hour — it is not instant when the configured date arrives.
3. If the status is failed, check the history for the error detail.
4. Verify the Koru license was active at the expected moment: the cron skips the run (without marking the job as failed) if the license isn't authorized at that time.

The license shows as inactive

1. Compare the Website ID with the correct site in Koru Suite.
2. Confirm Koru Catalog Boost is active for that website.
3. Verify you didn't copy extra spaces.
4. Retry the validation.
5. If it persists, report the Website ID, account, and workspace to support, without sending credentials.

For production technical support:

vtex logs {account}.catalogo-boost

Don't share tokens, cookies, or data that isn't necessary for diagnosis.

Functional limits

The current version:

• Never deletes categories: retiring one is always deactivation (IsActive=false).
• Does not reparent categories directly (a VTEX Catalog API restriction); the "Relocate" workaround creates a copy and deactivates the original, not an in-place move.
• Brand logos are uploaded only via dropzone, not by spreadsheet, and VTEX only accepts JPG/GIF (other formats are automatically converted to JPG).
• Image "replace" is not atomic: it deletes the existing image first, then creates the new one.
• Scheduled image visibility depends on a cron that runs once per hour, not in real time.
• A relocation with very many products to migrate could exceed the route's time limit; in that case, the migration stays incomplete and must be retried.
• History keeps the last 500 operations, and the scheduled-visibility queue holds up to 1,000 jobs.
• Its interface is in Spanish, regardless of the language configured on the VTEX account (the VTEX Admin menu labels are translated to Spanish/English/ Portuguese).
• Does not integrate with VTEX OMS or Master Data: it operates exclusively on the Catalog API (categories, brands, products, and SKU images).
• Always operates on the VTEX account where it's installed; it does not manage another account's catalog from a single installation.

Checklist before operating

• Koru Catalog Boost installed on the correct account and workspace.
• Store's Website ID verified.
• Active license confirmed.
• User has Catalog - Full access in their License Manager role.
• Defaults for new categories (categoryDefaults) reviewed.
• Templates downloaded and test spreadsheets validated in each module.
• A test category upload validated in the preview before applying in bulk.
• A test relocation executed and checked against the detailed result.
• Automatic logo matching reviewed before uploading in bulk.
• Scheduled visibility for at least one image tested end to end.
• History reviewed after each test operation.
• An owner assigned to periodically review the operation history.