Cupones Masivos

Create and archive VTEX coupons in bulk from the Admin, with unique codes, per-coupon reporting, and CSV export.

vtex install soluciones4fpartnerar.cupones-masivos@0.x

Cupones Masivos is a VTEX Admin App that solves a limitation of the native VTEX panel: it cannot generate coupons in bulk. The app creates N coupons from a base code — with a random suffix or sequential numbering — links them to a utmSource / utmCampaign, and archives them in bulk once the campaign ends. Every operation returns a per-coupon report and, for bulk creation, a CSV with the generated codes.

Unlike Koru's storefront apps, nothing is configured in the Koru panel and no site code is touched. Koru Suite is used only to enable the app's license for the store; the entire operation lives inside VTEX Admin.

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.
• VTEX permission to operate coupons (Promotions and Coupons module). Without it, every coupon fails with "No permission to operate coupons in VTEX."
• The ecommerce Website ID from Koru Suite, with Cupones Masivos active for that website.

Cupones Masivos does not create a custom VTEX role and uses no credentials of its own: it operates with the identity of the logged-in administrator. Human permissions are managed with VTEX's existing access controls (License Manager).

Identifiers you will encounter

Installation with the VTEX CLI

Installation uses the official VTEX CLI. It requires no Store Theme changes, no block declarations, no <script> snippet, and no Google Tag Manager setup: the app runs entirely inside VTEX Admin and its own Node service.

Install in a validation workspace first

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

vtex login {store-account}

vtex use {store-account}/{workspace}

vtex whoami

vtex install soluciones4fpartnerar.cupones-masivos@0.x

vtex list

Open the app in VTEX Admin

The app registers a Cupones Masivos item under the store setup section of VTEX Admin. You can also navigate directly to:

https://{workspace}--{store-account}.myvtex.com/admin/app/cupones-masivos

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

https://{store-account}.myvtex.com/admin/app/cupones-masivos

If that URL does not resolve in your account, try /admin/cupones-masivos: depending on the installed version, the app may expose the screen on either route. The stable entry point is always the Admin menu item.

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 soluciones4fpartnerar.cupones-masivos@0.x
vtex list

Settings belong to each installation/workspace. Verify the Website ID in the final environment even if you already tested it 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 soluciones4fpartnerar.cupones-masivos@0.x
vtex list

After updating, open the app and verify that the license is still active and the Website ID is present.

Uninstall

Uninstallation applies to the current workspace:

vtex whoami
vtex uninstall soluciones4fpartnerar.cupones-masivos
vtex list

Uninstalling the app does not archive or delete the coupons already created: they still exist in VTEX and are managed from the native Promotions and Coupons module.

Activation and first access

Get the Website ID

Before first use, Red Clover must activate Cupones Masivos 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 VTEX store where the 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 + Cupones Masivos combination has an active license.

Available app settings

koruAppId can only be set from VTEX's native settings; the app's connection screen writes the Website ID only.

Verify the license from the browser

With an open Admin session, in the same tab and domain:

GET https://{store-account}.myvtex.com/_v/private/cupones-masivos/health

{
  "ok": true,
  "appId": "soluciones4fpartnerar.cupones-masivos",
  "account": "{store-account}",
  "workspace": "master",
  "checkedAt": "2026-07-30T12:00:00.000Z",
  "license": {
    "configured": true,
    "authorized": true,
    "reason": "koru"
  }
}

Before creating the first batch

In VTEX the discount lives in the promotion, not in the coupon. The correct order is:

Creating coupons

Everything is handled from VTEX Admin → Store settings → Cupones Masivos. There is a single screen with an Operation selector in the upper right:

Code strategy

The codeStrategy field defines how each code is assembled: {prefix}{separator}{suffix}.

The random suffix uses a readable alphabet without ambiguous characters:

ABCDEFGHJKMNPQRSTUVWXYZ23456789

0/O and 1/I/L are excluded so the code can be dictated over the phone or transcribed by hand without errors.

Below the fields, the app shows a live preview (Example: RedClo-00001) that updates as you change the prefix, separator, and length.

Code parameters

Coupon parameters

These apply equally to every coupon in the batch.

The form shows a permanent notice: "The coupon only applies a discount if a VTEX promotion is bound to this UTM source and campaign."

Overwrite protection

Before creating each coupon, the backend checks whether the code already exists in VTEX. If it does, it is not overwritten: that item is reported as "Coupon already exists." and the rest of the batch continues.

This is deliberate. VTEX's coupon POST is an upsert: without this check, a new campaign could silently overwrite the configuration of an active coupon.

Archiving coupons

Archiving uses VTEX's dedicated endpoint, one coupon per request. A nonexistent code returns "Coupon does not exist." for that item without aborting the rest.

Results and export

A results block appears after every operation:

CSV columns: couponCode, utmSource, utmCampaign, maxItemsPerClient, expirationIntervalPerUse.

A bulk operation never fails entirely because of a single coupon: each one is resolved separately and the response aggregates the counters.

Operation limits

The 500 limit is validated on creation. For archiving, the backend only requires at least one code, but avoid going beyond a few hundred per operation: with a 60 s timeout and 8 in parallel, a very large batch is cut off by time.

For more than 500 coupons, run several operations. With sequential it is straightforward: raise sequenceStart to the next number of the previous batch — batch 1 from 1, batch 2 from 501. With random, simply repeat the operation: codes are checked against the store before being created, so there is no risk of a silent collision.

License and security

License validation

Every operational route requires:

1. A valid VTEX Admin session. Without it, the backend responds 401.
2. An active Koru license for the Website ID and the Cupones Masivos App ID.

The backend exposes its routes under /_v/private/cupones-masivos/*. They are private: they cannot be consumed from the storefront or by an external client without an admin session.

To tolerate transient failures:

• A positive authorization is cached for 5 minutes; an explicit revocation for 60 seconds.
• If Koru Suite does not respond due to a network or server error, a previous positive validation can keep access alive for up to 72 hours.

These values are internal, are not configurable per store, and there is no manual cache purge: after activating the license or fixing the Website ID, wait for the TTL and reload the screen.

Data and credentials

• The app does not request or store the merchant's AppKey/AppToken: it operates with the identity of the logged-in administrator.
• There are no Koru secrets in the browser; license validation is resolved server-side.
• The only persisted data are the koruWebsiteId and koruAppId settings — neither is a secret — and an internal record of the last positive validation.
• It stores no customer data and no batch history.
• It injects no JavaScript, CSS, or blocks into the storefront and does not participate in public page rendering or checkout: it does not affect store performance.

Troubleshooting

The app does not appear after installing

1. Run vtex list and look for soluciones4fpartnerar.cupones-masivos.
2. Run vtex whoami and confirm the account and workspace. If the app was linked in a development workspace, it does not appear in master.
3. Reload VTEX Admin: the menu is cached on the browser side.
4. Open /admin/app/cupones-masivos or /admin/cupones-masivos directly.

The app says "Koru license not active"

Koru answered that this website_id + app_id combination does not have the app enabled. Check:

1. That koruWebsiteId belongs to this ecommerce website. This is the most common mistake: pasting the Website ID of another store of the same client.
2. That the app is active for that website in Koru Suite.
3. That you did not copy any spaces.
4. That koruAppId is empty, unless Koru explicitly told you otherwise.

The app says "We could not verify the license"

This is a transient availability state, not proof of revocation. The backend tolerates network outages: if there was a positive validation within the last 72 hours, operations remain enabled. Retry in a few moments.

I activated the license and the app is still blocked

Validation is cached. Wait for the corresponding TTL — 5 minutes for an active license, 60 seconds for a revoked one — and reload the Admin screen. There is no manual purge endpoint.

The coupons were created but discount nothing

This is not an app problem. In VTEX a coupon only activates promotions whose scope listens for its utmSource / utmCampaign. In Admin → Promotions, create a promotion with a UTM parameter condition pointing to the same source and campaign, in lowercase.

A coupon failed with "Coupon already exists."

The code is already in the store and the app does not overwrite existing coupons by design. Change the prefix, raise sequenceStart, or increase the random suffix length.

I requested 100 coupons and fewer were created, with no errors

This happens with random and very short suffixes: the combination space runs out. The alphabet has 30 symbols, so a 1-character suffix yields at most 30 distinct codes. The app deduplicates and creates only the unique codes it managed to generate.

Fix: increase suffixLength or reduce quantity. Always compare the requested amount with the Requested counter in the results.

Several coupons failed with "VTEX rate limit reached."

The coupon API applied rate limiting and the 3 retries were exhausted. Retry those codes later or split the work into smaller batches.

Every coupon fails with "No permission to operate coupons in VTEX."

The logged-in admin user has no permission over the Promotions and Coupons module. The app operates with that identity, not with its own credentials: request the corresponding role in License Manager and sign in again.

Raw identifiers appear on screen

If you see text such as create.title instead of a label, the workspace message catalog is out of date. Re-link or reinstall the app.

For technical support in production:

vtex logs soluciones4fpartnerar.cupones-masivos

Do not share tokens, cookies, or unnecessary personal information.

Functional limits

The current version:

• Creates and archives coupons; it does not create or edit promotions.
• Does not list, search, or export the store's existing coupons: it works by code.
• Does not overwrite existing coupons.
• Keeps no history of generated batches.
• Does not undo an archive.
• Supports up to 500 coupons per creation operation.
• Allows letters, numbers, and hyphen only in the code.
• Accepts only hh:mm:ss in the expiration interval.
• Is a single Admin screen per account: it does not support multiple instances.
• Is available in Spanish, English, and Portuguese, following the VTEX Admin language; it has no language setting of its own.

Checklist before operating

• Cupones Masivos installed in the correct account and workspace.
• Store Website ID verified and koruAppId empty.
• Active license visible in the header.
• Admin user with permission over Promotions and Coupons.
• Promotion created in VTEX with the UTM parameter condition.
• utmSource and utmCampaign agreed, without spaces and in lowercase.
• Code strategy chosen and live preview reviewed.
• quantity within the 500-per-operation limit.
• suffixLength large enough for the requested amount, if using random.
• Requested counter compared with the amount you asked for.
• CSV exported and stored before closing the screen.
• One coupon from the batch tested at checkout.
• Owner defined for archiving the coupons when the campaign ends.