Tagger (Bulk Customer Tagging by Zip Code)¶

Menu Location: Customers > Misc > Tagger

Last Updated: 2026-07-26

Overview¶

Tagger lets you apply a Customer Tag to every customer whose shipping zip code appears on an uploaded CSV list. Instead of tagging customers one at a time, you upload a list of zip codes, give the group a tag name, and the system finds every customer currently shipping to one of those zips and tags them.

Today Tagger only matches on shipping zip code. It is built to support other match types in the future (there is a "Data Type" selector on the page), but shipping zip is the only option currently available.

Primary Functions:

Create a new Customer Tag and assign it to all customers in a list of zip codes
Re-run the same zip match later to catch customers who signed up since the last upload
Keep the tag in sync automatically: if a tagged customer's shipping zip changes, the tag is added or removed to match their current zip

Page Layout¶

Upload CSV and Apply Tag form: a CSV file picker, a "Data Type" dropdown (currently only offers subscriptions.shipping_zip), and a "Tag Name" text field, with an Upload button.
Apply Tagger button: re-runs the zip match against whatever is currently in the tool, without needing a new file. Use this to pick up customers who joined after the last upload.
Below the form, previously uploaded zip entries are listed, each one linked to the Customer Tag it belongs to.

CSV File Format¶

The only requirement is a header row containing a column literally named "Zip Code" or "zip" (not case-sensitive). Every other column in the file is ignored.

Example CSV:

Zip Code
02138
02139
02140

If no column matches "Zip Code" or "zip", the upload is rejected with "Zip Code column not found in the CSV file."

Uploading and What Happens¶

Steps:

Prepare a CSV with a "Zip Code" (or "zip") column listing the zip codes you want to target.
Go to Customers > Misc > Tagger.
Choose the file, leave Data Type on subscriptions.shipping_zip, and type a Tag Name.
Click Upload.

What the system does, in order:

Creates a brand-new Customer Tag with the name you typed. It does not check whether a tag with that name already exists, so uploading with a name you've used before creates a second, separate tag of the same name rather than reusing the original.
Clears out every previously uploaded zip-code tag mapping first. Because shipping zip is currently the only supported match type, uploading a new list replaces the whole active zip-tagging set, not just entries for the tag you're creating. Only the most recently uploaded list stays in effect; earlier zip-based tags stop being reapplied to new customers, and the tag is removed from anyone it was already applied to.
Stores each zip code from the CSV against the new tag.
Matches every customer whose current shipping zip is on the list and applies the tag to them (skipping anyone who already has it).

On success you'll see "CSV file processed successfully and tag applied!" Other possible messages: "Please upload a CSV file." (no file selected), "Failed to open the CSV file.", or "Failed to create a new tag in promotions_tags." There is no preview, validation summary, or per-row success/error report, just this one message after processing.

Apply Tagger (the button next to the upload form) reruns step 4 above using whatever zip lists are currently stored, without touching the tag list itself. Use it to catch customers who moved into a tagged zip or signed up after your last upload.

Keeping Tags in Sync¶

Once a zip-based tag exists, it stays current automatically: whenever a customer's shipping zip is saved (on their Customer Detail page in admin, or when the customer updates their own delivery address), the system checks their new zip against the tag's stored value, removes the tag if it no longer matches, and applies it if it now does.

Common Use Cases¶

Tag customers in a growing delivery area¶

Export the list of zip codes in a new delivery zone, upload it with a tag name like "NewZone-Q3", and use that tag to target those customers for a launch email or promo.

Tag a marketing campaign's zip footprint¶

If a promotion is being run in specific zip codes, upload that zip list under a campaign tag name (e.g. "Promo-Spring2026"), then use the tag to filter and message that group from the Customers page.

Troubleshooting¶

Upload says "Zip Code column not found in the CSV file."¶

The header row doesn't contain a column named exactly "Zip Code" or "zip". Rename the column and re-upload.

Upload says "Please upload a CSV file."¶

No file was selected, or the browser failed to attach it. Choose the file again before clicking Upload.

A new upload seems to have removed an older tag from customers¶

This is expected, not a bug: uploading any new zip list clears out all previously uploaded zip-tag mappings (see "Uploading and What Happens" above), because shipping zip is currently the only supported match type. If you need both tag groups active, keep a combined zip list rather than uploading them separately.

Customer doesn't have the tag even though their zip is on the list¶

Click Apply Tagger to re-run the match. Also confirm the customer's shipping zip on their Customer Detail page actually matches an entry from the uploaded list.

Customers - the customer list has a "Select tag..." filter that shows customers with (or without) a given Customer Tag.
Customer Detail - shows the tags on that individual customer, and has an "Edit all tags" link to the Customer Tags page.
Customer Tags (admin-edit.php?table=promotions_tags) - rename a tag or add a description to it after it's been created by Tagger.
Weekly Report by Tag - filters the weekly report to customers carrying a given tag.

Quick Reference Card¶

Task	Action/Location
Upload a new zip list and create a tag	Choose File, type Tag Name, click Upload
Re-check for newly matching customers	Click "Apply Tagger"
View which customers have a tag	Customers page > "Select tag..." filter
Rename a tag / add a description	Customer Tags page (`admin-edit.php?table=promotions_tags`)
See a customer's tags	Customer Detail page

FAQs¶

Can I remove a tag from customers through this page?¶

No. Tagger only adds tags by uploading a zip list. Uploading a new list does remove the previous zip-based tag from customers (see the warning above), but there's no "remove this tag" action here.

What happens if I type the same Tag Name I used before?¶

A new, separate tag is created. The tool doesn't check for or reuse an existing tag with the same name.

Can I match on something other than zip code?¶

Not currently. The Data Type field only offers subscriptions.shipping_zip.

Will the tag stay accurate if a customer moves?¶

Yes. When a customer's shipping zip is updated, the tag is automatically added or removed to match whether their new zip is on the uploaded list.

Change Log¶

2026-07-26¶

Rewritten against the actual tagger page (kiv/admin-edit.php?table=tagger, backed by the tagger, promotions_tags, and promotions_tagging tables). Removed invented customer_id/email CSV workflow, validation/preview/results UI, tag-removal-by-CSV, and the Permissions & Access section, none of which exist in the code.

2026-03-01¶

Initial documentation created