Categorization Status Indicators

Categorify uses color-coded status badges to communicate categorization outcomes at a glance. These visual indicators help you quickly identify successful categorizations, lower-confidence results, and issues that need attention.

Where Status Indicators Appear

Status badges appear throughout Categorify to give you immediate feedback:

Dashboard - Latest Categorizations: Each recent categorization shows a status badge next to the assigned category, letting you monitor results as they complete.

History Page - Status Column: The History table includes a Status column with badges for every categorization request. Scan your history to identify patterns across multiple products.

Categorization Details Modal: When you click to view details of a specific categorization, the status badge appears prominently alongside the full categorization information.

The badges use consistent colors across all locations, so once you understand what each color means, you can interpret results throughout Categorify.

Understanding Status Badges

Categorify uses four status badges:

Succeeded - Green or yellow background depending on confidence level
Not found - Gray background
Error - Red background

Let’s explore what each status means and how to respond.

🟢 Green: AI-Selected Category (Succeeded)

What It Means

The AI confidently selected this category from the available options. This is the ideal outcome—the system analyzed your product description, evaluated potential categories, and determined this specific category is the best match.

Technical details:

• The AI actively chose this category during the selection phase of the pipeline
• The category selection is based on semantic understanding, not just similarity scores
• No fallback mechanism was needed

When You See This

Green badges represent your most reliable categorizations. The AI evaluated the product description and any custom AI instructions you provided, then made a confident determination.

What to Do

For products with green badges:

1. Verify the category matches your expectations - Even confident AI selections can occasionally miss nuances specific to your business
2. Note successful patterns - Products that get green badges have descriptions the AI understands well
3. Use as examples - When writing descriptions for similar items, model them on products that receive green badges

Accuracy and Expectations

Green badges are objectively accurate based on the available information in the product description. The AI doesn’t use implicit knowledge (like what your store typically sells or which products are most common).

In stores with great product descriptions:

• 90-95% of categorizations receive green badges
• Self-contained descriptions consistently produce green results
• Clear product information leads to confident AI decisions

Strategies for More Green Results

If you’re getting fewer green badges than desired:

Improve product descriptions - The AI needs sufficient context to make confident decisions. Add:

• Specific product features and characteristics
• Material information
• Use cases or target audience
• Brand name and model number when relevant

Compare products that get green vs. yellow/gray badges to identify what information makes the difference.

Add custom AI instructions - If similar products consistently get yellow or gray badges due to legitimate ambiguity, write custom instructions that provide disambiguation rules. See Writing AI Instructions for detailed guidance.

Test incrementally - After improving descriptions or adding instructions, re-categorize the same products to verify your changes increased green results.

🟡 Yellow: Top-Ranked Category (Succeeded)

What It Means

The AI couldn’t confidently choose between multiple categories, so the system returned the option with the highest relevance score. This is a fallback mechanism that prioritizes coverage over precision.

Technical details:

• The AI reached the fallback phase of the pipeline
• Requires “Use best-guess category” setting to be enabled
• Based on semantic similarity scoring rather than AI selection

When You See This

Yellow badges indicate ambiguity. The product description didn’t provide enough information for the AI to distinguish between similar categories, or multiple categories legitimately fit the product equally well.

Important: Yellow badges only appear when you have “Use best-guess category if AI cannot decide” enabled in Settings. If this setting is disabled, these same categorizations would show gray badges instead (no category found).

What to Do

Yellow results require more attention than green results:

1. Review the category - The top-ranked category may still be correct, but verify it matches your expectations
2. Check for recurring patterns - If many similar products get yellow badges, you need a systematic solution
3. Prioritize for review - In bulk categorizations, manually verify yellow results before finalizing

Strategies for Reducing Yellow Results

Yellow badges signal improvement opportunities. Here’s how to turn them green:

Add distinguishing details to descriptions

Yellow results often occur because similar categories have comparable scores and the description doesn’t provide distinguishing information.

Example:

Description: "iPhone 16 Pro smartphone"
Result: 🟡 Yellow - Mobile Phones

The AI can’t determine if this is an unlocked phone, contract phone, or pre-paid phone because those details aren’t in the description.

Improved description:

"iPhone 16 Pro unlocked smartphone"
Result: 🟢 Green - Unlocked Mobile Phones

Write custom instructions for recurring patterns

If the same type of product consistently gets yellow badges, add an instruction that resolves the ambiguity:

For phones without contract information, default to unlocked unless
description explicitly states contract or pre-paid.

After adding this instruction, re-categorize affected products. Many should turn from yellow to green.

Accept strategic yellow results

Not all yellow badges need fixing. In some situations, yellow results are acceptable:

• Initial catalog imports where you’ll review results manually anyway
• High-volume operations where some imprecision is tolerable
• Products with inherent ambiguity that even humans struggle to categorize

Focus your optimization efforts on high-value products or recurring patterns rather than trying to eliminate every yellow badge.

⚫ Gray: No Category Found (Not Found)

What It Means

The AI cannot confidently select a category, and no fallback mechanism is available. The system returns no category rather than guessing.

Technical details:

• The AI reached the fallback phase but “Use best-guess category” is disabled
• All category fields remain empty
• This is the most conservative outcome—no guess is made

When You See This

Gray badges indicate the AI lacks sufficient information to make any determination, or the product doesn’t fit the taxonomy well.

Common Causes

Non-self-contained descriptions - The typical cause is that the product description doesn’t explicitly state:

• What the product is
• What it’s made of
• Who it’s for
• Key characteristics

Example of a gray result:

"Wednesday Addams meets The Night Gardener in the sequel to the
bestselling Millie Fleur's Poison Garden. A delightfully peculiar
story about embracing the magic of the night."

This never explicitly says “book” or “novel”—it assumes you already know.

Taxonomy gaps - Occasionally, products in certain niches suffer from gaps in Shopify’s taxonomy. Highly specialized or emerging product categories may not be well-represented.

What to Do

Gray results require action before products can be properly categorized:

1. Examine the product description - Is there enough context for categorization?
2. Check if the product fits the taxonomy - Some products may be outside the taxonomy’s scope
3. Determine if manual classification is needed - Some products may require human judgment

Strategies for Reducing Gray Results

Gray badges point to fundamental issues with either the description or taxonomy fit:

Enhance product descriptions significantly

Add comprehensive details that explicitly state:

• What the product is (don’t just imply it)
• Primary materials
• Key features or functions
• Target audience or use cases
• Brand/model when relevant

Example improvement:

Before (Gray): "Wednesday Addams meets The Night Gardener..."
After (Green): "Children's fiction book: Wednesday Addams meets
The Night Gardener... Hardcover, 256 pages, ages 8-12."

Verify taxonomy fit

Some products may not fit well in standard taxonomies:

• Highly specialized niche products
• Multi-purpose products spanning multiple categories
• New product types not yet in the taxonomy

For products that don’t fit, either classify them manually into the closest reasonable category or contact support about taxonomy coverage gaps.

Enable fallback temporarily for diagnostics

If you’re getting many gray results:

1. Enable “Use best-guess category” to convert gray to yellow
2. Review the yellow results to see what categories are suggested
3. Use these suggestions to understand what information the AI needs
4. Improve descriptions based on the patterns you see
5. Disable fallback and re-categorize to check if they’re now green

Warning: Lots of Gray Results

If you’re seeing predominantly gray badges, it indicates structural problems:

Description quality issues - Your product descriptions lack the detail needed for automated categorization. This is fixable by enhancing descriptions.

Catalog-taxonomy mismatch - In rare cases, if most products return gray even with detailed descriptions, your product catalog may not be suitable for AI-based categorization using Shopify’s taxonomy. This might occur with highly specialized stores selling niche products outside typical e-commerce categories.

🔴 Red: Error Occurred (Error)

What It Means

A technical error prevented the categorization request from being processed. This is not a categorization outcome—it’s a technical failure that stopped categorization before it could complete.

When You See This

Red badges signal technical problems that need attention. Unlike other statuses, red doesn’t represent a categorization outcome—it means the request failed.

Common Causes

Most red errors relate to temporary unavailability of services in the categorization pipeline:

• AI service outages
• Network connectivity issues
• Processing timeouts
• Infrastructure problems

Categorify has redundancy in place for all services, but outages can still occur occasionally.

What to Do

Red results need troubleshooting:

For individual red badges:

1. Click the Re-categorize button in the Latest Categorizations pane or History page
2. The product will be queued for categorization again
3. If it succeeds the second time, the issue was temporary

For many red badges:

If you see multiple red badges appearing simultaneously:

1. Check if there’s an ongoing service outage
2. Wait 10-15 minutes for automatic recovery
3. Try re-categorizing a few products to test if service is restored

If problems persist:

Contact support at support@categorify.app if:

• Red badges continue appearing after 30 minutes
• Re-categorization repeatedly fails for the same products
• The system doesn’t recover automatically

Include the Request IDs from affected categorizations to help support investigate.

Credits and Errors

Important: Red badges mean no credit was consumed. Since the categorization pipeline didn’t run, no computational resources were used, and your credit balance is unchanged.

Status Patterns and What They Mean

The distribution of status badges across your categorizations reveals important insights about your catalog and configuration.

Healthy Patterns

For most stores with good product descriptions and appropriate settings:

70-90% green badges - Majority of products are confidently categorized5-20% yellow badges - Some ambiguity that may be acceptable0-10% gray badges - Few products need manual handling or description improvementUnder 1% red badges - Minimal technical errors

This distribution indicates the AI has sufficient information to make confident decisions for most products, with acceptable ambiguity for a small portion.

Warning Signs

Watch for these patterns that indicate issues:

Too many yellow badges

If 40%+ of categorizations are yellow, it means:

• Many products would return “no category” if fallback were disabled
• Descriptions lack distinguishing details
• These products need attention even though they have categories assigned

Action: Yellow badges might be acceptable for an initial bulk categorization run, but investigate patterns and improve descriptions for recurring issues. Consider whether yellow results are meeting your quality standards.

Predominantly gray badges

If most categorizations return gray:

• Product descriptions are structurally lacking detail
• The AI can’t find enough information to categorize
• In extreme cases, the catalog may not suit AI-based categorization

Action: Significantly enhance description quality by making them self-contained. If improvements don’t help, some catalogs may require manual categorization or custom taxonomy solutions.

Sudden red badges

Multiple red badges appearing at once indicate:

• Service outage affecting categorization
• Infrastructure problems
• External dependency issues

Action: Wait for automatic recovery (usually 10-30 minutes). Contact support if red badges persist beyond 30 minutes.

Tracking Improvements

As you optimize descriptions and settings, monitor status distribution changes:

Positive trends:

• Increasing percentage of green badges over time
• Decreasing yellow and gray badges for similar product types
• Consistent results when re-categorizing improved products

Negative trends:

• Increasing yellow or gray badges for new products
• Inconsistent results for similar items
• Declining green badge percentage

Use the History page’s status filter to track these trends and identify which product types need attention.

Filtering by Status

The History page lets you filter categorizations by status to focus on specific outcomes:

1. Open History in Categorify
2. Use the Status filter dropdown
3. Select the badge type you want to view:

• Succeeded (green/yellow combined)
• Not found (gray)
• Error (red)
• All statuses (no filter)

This helps you:

• Review all yellow results for quality checking
• Find all gray results that need description improvements
• Identify error patterns if multiple categorizations failed
• Focus on specific outcomes during bulk operations

Status Changes Over Time

A product’s categorization status isn’t permanent—it can change if you re-categorize the product.

When Status Can Change

Product description updated

If you improve a product description and automatic categorization is enabled, the product will be re-categorized automatically. A gray result might become green with better information.

Manual re-categorization

If you manually re-categorize a product (using any of the categorization methods), a new status is assigned based on the current description and settings.

Settings adjusted

If you change settings like “Use best-guess category” and re-categorize:

• Yellow badges might become gray (if you disable fallback)
• Gray badges might become yellow (if you enable fallback)
• Gray badges might become green (if you add helpful AI instructions)

Significant Improvements

Well-written description improvements can dramatically change outcomes:

Before improvement (Gray):

"Wednesday Addams meets The Night Gardener in the sequel..."

After improvement (Green):

"Children's fiction book featuring Wednesday Addams...
Middle-grade novel, hardcover, 256 pages, ages 8-12."

The status change from gray to green confirms that the enhanced description provided sufficient information for confident categorization.

Next Steps

Now that you understand status indicators:

• How Categorization Works - Understand the pipeline that produces these statuses
• Configuring Settings - Adjust settings to influence which statuses appear
• Writing AI Instructions - Reduce yellow and gray badges with custom guidance
• Categorization Strategies - Choose approaches that produce your desired status distribution
• Viewing Categorization History - Use status filters to analyze patterns

Ready to improve your results? Start with Writing AI Instructions to guide the AI’s decision-making for ambiguous products.