Skip to main content
Tutorial

Tutorial: Customer Profile Tags and Properties

Introduction​

Customer Tags and Properties in UltraCart provide a flexible system for segmenting, enriching, and automating customer data. These tools are foundational for personalization, marketing campaigns, reporting, and integrations.

This guide covers:

  • The difference between Tags and Properties

  • How to manage them in the UltraCart UI

  • How to report on Tags and Properties

  • How to use the REST API for bulk updates

  • How to build campaigns using Tags and Properties

  • Frequently Asked Questions

Note: Tags and Properties are internal data structures and are not visible to customers unless explicitly used in templates.

Prerequisites​

Before working with Tags and Properties, ensure:

  • You have access to Customer Profiles

  • Your user account has permissions to:

    • View and edit customer profiles

  • (Optional) For API usage:

    • API Key configured under Merchant → Configuration → API Access

    • Familiarity with REST API or SDK usage

What Are Tags and Properties?​

Customer Tags​

Customer Tags are simple labels used to categorize customers.

  • Single string value (e.g., VIP, Wholesale)

  • Multiple tags per customer allowed

  • Ideal for segmentation and campaign targeting

Common use cases:

  • Lifecycle stages: New_Customer, At_Risk, Churned

  • Value tiers: VIP, High_Value

  • Programs: Loyalty_Member, Affiliate

  • Migration: Imported, Legacy_System

Customer Properties​

Customer Properties store structured data as key-value pairs.

  • Include Name + Value

  • Optional expiration date

  • Used for personalization, analytics, and automation

| Feature | Tags | Properties |

MetricRecommendation
Total unique tagsKeep under ~50
% customers taggedAim for >50% coverage
Tags per customerIdeal: 2–5
Naming consistencyStandardize (e.g., VIP only)
Expiring propertiesReview regularly

AI Export Business Analysis Prompt​

Overview​

The AI Export Business Analysis Prompt is designed to transform exported customer tag and property data into actionable business insights.

This prompt is intended for use with AI tools (such as ChatGPT or other LLM-based analysis tools) after exporting customer data via:

  • Customer Profile export (CSV)

  • Data Warehouse (BigQuery query results)

The analysis helps merchants:

  • Evaluate segmentation effectiveness

  • Identify data quality issues

  • Discover personalization opportunities

  • Improve marketing and automation strategies

Tip: This is especially useful for large datasets where manual analysis is impractical.

Purpose of This Report​

The AI-generated report provides:

  • Segmentation Health Analysis

    • Tag coverage and distribution

  • Data Quality Assessment

    • Naming inconsistencies, duplicates, missing data

  • Customer Insights

    • High-value segments, lifecycle gaps

  • Actionable Recommendations

    • Campaign ideas, automation triggers, cleanup tasks

This enables merchants to move from raw data → strategic decisions quickly.

AI Analysis Prompt​

Use the following prompt when submitting your exported data to an AI tool:

You are an expert analyst specializing in UltraCart customer data segmentation.

You will receive JSON data representing customer profiles, including tags and properties.

Analyze the data and provide a structured report with actionable insights.

Focus on the following areas:

1. Customer Segmentation Overview
- Count unique tags
- Identify most common tags
- Calculate percentage of customers with tags
- Identify customers with multiple tags
- Detect naming inconsistencies (e.g., VIP vs vip)

2. Property Analysis
- Identify most common properties
- Categorize property types (loyalty, behavioral, attribution, etc.)
- Analyze property value patterns
- Identify expiring or expired properties

3. Data Quality Assessment
- Detect duplicate or inconsistent naming
- Identify customers with no tags or properties
- Flag rarely used properties (<1% usage)
- Highlight expired properties

4. Segmentation Strategy Insights
- Identify gaps in lifecycle segmentation (new, active, churned)
- Identify missing value-based segmentation (VIP, high-value)
- Suggest improvements

5. Personalization Opportunities
- Recommend campaign targeting strategies
- Suggest automation triggers using properties
- Identify opportunities for customer experience personalization

6. Key Metrics to Report
- Total unique tags
- Average tags per customer
- Tag coverage %
- Total unique properties
- Average properties per customer
- Customers without tags or properties

7. Output Format
Provide:
- Executive Summary (3–4 sentences)
- Segmentation Health Score (Coverage, Consistency, Strategic Value)
- Tag Analysis
- Property Analysis
- Data Quality Issues
- Strategic Recommendations (High, Medium, Long-term)
- Example Campaign Use Cases

Focus on actionable insights that improve segmentation, personalization, and revenue.

When to Use This Prompt​

Use this AI prompt when:

  • Reviewing post-migration customer data

  • Auditing tag/property consistency

  • Planning new marketing campaigns

  • Evaluating segmentation maturity

  • Identifying data cleanup opportunities

Example Workflow​

  1. Export customer data (CSV or JSON)

  2. Convert to JSON (if needed)

  3. Paste into AI tool with the prompt above

  4. Review generated insights

  5. Implement:

    • Tag standardization

    • Property enrichment

    • Campaign strategies

REST API Usage​

Authentication​

  • API Key required

  • Include expansion:

tags,properties

PHP Example​

$customer->setTags([$tag1, $tag2]);
$customer->setProperties([$prop1, $prop2]);

$expansion = "tags,properties";
$api->insertCustomer($customer, $expansion);

Important: Always pass model objects (CustomerTag, CustomerProperty) — not strings.

JavaScript Example​

customer.tags = [tag1, tag2];
customer.properties = [prop1, prop2];

await api.insertCustomer(customer, { _expand: 'tags,properties' });

Updating Existing Customers​

  1. Retrieve existing customer

  2. Merge tags/properties

  3. Update customer

Warning: setTags() replaces all tags. Always merge first.

Bulk Import Pattern​

  • Loop through customers

  • Assign:

    • imported tag

    • legacy_id property

  • Respect API rate limits

Using Tags & Properties in Campaigns​

Workflow Overview​

  1. Define segment (e.g., VIP)

  2. Create segment in UltraCart

  3. Create campaign or flow

  4. Attach segment

  5. Configure triggers

  6. Activate and monitor

Example Use Cases​

VIP Campaign

  • Trigger: Tag = VIP

  • Send exclusive offers

Re-engagement

  • Trigger: Property Days_Since_Last_Order > 90

  • Send win-back emails

Post-import onboarding

  • Trigger: Tag = imported

  • Send welcome sequence

Automation Strategy​

Use scheduled scripts to:

  • Update lifecycle tags (active, at_risk, churned)

  • Update properties (LTV, days since order)

FAQ​

What is the difference between a Tag and a Property?​

Tags are labels for segmentation. Properties store structured data for logic and personalization.

Where do I see tags and properties?​

  • Tags: Activity Tab → Lists & Segments

  • Properties: Activity Tab → Information Panel

Why didn’t my property save?​

You likely added multiple entries without saving. Save each property individually.

Why are my API tags/properties empty?​

Your expansion string is missing tags,properties.

Can customers see tags or properties?​

No. They are internal unless explicitly used in templates.

Can tags expire?​

No. Only properties support expiration.

Does the API overwrite tags?​

Yes. Always fetch and merge existing tags before updating.

How do I use tags in campaigns?​

Create a Segment, then assign it as the campaign audience.

Is there a limit to tags or properties?​

No hard limit, but best practice:

  • 2–10 tags per customer

What naming convention should I use?​

Use:

Title_Case_With_Underscores

Example: Loyalty_Member

  1. Import via API

  2. Add imported tag

  3. Store legacy_id property

  4. Validate data

  5. Launch onboarding campaign

Conclusion​

Customer Tags and Properties provide a powerful foundation for segmentation, personalization, and automation within UltraCart. When used consistently, they enable scalable marketing strategies and deeper customer insights.

Next Steps​

  • Create standardized tag naming conventions

  • Build core customer segments

  • Implement automation scripts

  • Launch campaigns based on lifecycle stages

  • Explore Data Warehouse reporting

Was this page helpful?