Custom Attributes allow you to enrich your Churnkey implementation with additional customer data beyond the standard Stripe subscription data that we automatically collect. This data can be used for creating targeted flows and personalizing customer communications.

Overview

Built-in Stripe Data

Churnkey automatically pulls the following data from your Stripe subscriptions:

Subscription details (plan name, price, billing interval)
Product information
Subscription age and history
Customer billing details

Custom Attributes

Custom Attributes let you augment this built-in data with your own business metrics and customer information. They serve two main purposes:

Segmentation: Create targeted flows based on customer characteristics
Dynamic Communication: Personalize messages using customer-specific data

Setting Up Custom Attributes

1. Configure Attributes in Dashboard

Define your Custom Attributes in the Churnkey dashboard:

Navigate to Cancel Flow > Settings > Custom Attributes
For each attribute, configure:
- Name: The attribute identifier (e.g., storageUsed, activeProjects)
- Label: Display name used in the Churnkey dashboard
- Type: Data type (text, number, date, or boolean)

Example configuration:

Name: storageUsed Label: Storage Used (MB) Type: number

2. Send Attribute Data

There are two ways to send Custom Attribute data to Churnkey:

Method A: Stripe Metadata

Store attributes in Stripe metadata for use across all Churnkey products. You can add metadata to either:

The Stripe Customer object (for user-level attributes)
The Stripe Subscription object (for subscription-specific attributes)

Example Stripe metadata:

// On Customer object
{
  "metadata": {
      "totalStorageUsed": "1024",
      "accountHealth": "good",
      "lastLoginDate": "2024-03-15"
      }
}

// On Subscription object
{
  "metadata": {
     "seats_in_use": "45",
     "custom_features": "analytics,api_access"
     }
}

Method B: Direct Initialization (Cancel Flow Only)

For cancel flows, you can also send dynamic attributes during initialization:

document.getElementById('cancel-button').addEventListener('click', function () { window.churnkey.init('show', {
    subscriptionId: 'SUBSCRIPTION_ID',
    customerId: 'CUSTOMER_ID',
    authHash: 'HMAC_HASH',
    appId: 'YOUR_APP_ID',
    mode: 'live',
    provider: 'stripe',
    record: true,
    customerAttributes: {
      storageUsed: 1024,
      activeProjects: 12,
      lastLoginDate: "2024-03-15"
    }
   }
  )
 }
)

Data Format Requirements:

Strings: Must be in quotes (e.g., "good")
Numbers: Send directly without quotes (e.g., 1024)
Dates: Use ISO 8601 format (e.g., "2024-03-15")

Using Custom Attributes

Once configured and populated with data, you can use Custom Attributes in two ways:

1. Creating Segments

Go to Cancel Flow > Flows
Click Add Flow
In the flow builder:
- Name your audience
- Set conditions using built-in Stripe data and/or Custom Attributes
- Configure the flow for this segment

2. Dynamic Messaging

Navigate to your flow editor
Open any Rich Text Editor field
Click the Insert Variable button
Select from built-in Stripe data or your Custom Attributes

Best Practices

Personalized Messaging

Use Custom Attributes to create targeted messaging that resonates with your customers' specific situations:

Usage-Based Offers: "We noticed you've only used {{storageUsed}} MB of storage this month. How about 50% off your next month while you ramp up?"
Feature Adoption: "You haven't tried our {{unusedFeature}} feature yet. Would a free month help you explore its benefits?"
Account Health: "As a customer with {{activeProjects}} active projects, we'd love to understand what's not working for you."

Smart Segmentation

Combine Custom Attributes with built-in Stripe data to create sophisticated targeting:

Low Usage, High Value: Target enterprise customers who are paying for seats they're not using

Conditions: - Price > $500/month (Stripe data) - seats_in_use < 50% of purchased seats (Custom Attribute)

Feature Adoption: Identify customers who haven't adopted key features

Conditions: - Subscription age > 30 days (Stripe data) - last_feature_use < 7 days ago (Custom Attribute)

Engagement-Based Recovery: Tailor recovery emails based on usage patterns

Conditions: - Failed payment (Stripe data) - accountHealth: "active" (Custom Attribute) - lastLoginDate: within 7 days (Custom Attribute)

Example Workflows

Usage-Based Retention
- Track: Monthly active users, feature adoption rates
- Trigger: Show higher discounts to less active users
- Message: "We noticed your team's usage dropped last month. Let's get you back on track with 50% off."
Feature Education
- Track: Feature usage frequency, last feature interaction
- Trigger: Offer training for unused premium features
- Message: "Your Enterprise plan includes {{unusedFeature}}, which could help with {{businessGoal}}."
Account Health Intervention
- Track: Activity scores, support ticket history
- Trigger: Proactive outreach for declining engagement
- Message: "We see your team's {{activityScore}} has dropped. Would a consultation with our success team help?"

Troubleshooting

Common issues and solutions:

Attributes Not Appearing:
- For Stripe metadata: Verify the metadata is properly set and the keys match your configuration
- For initialization attributes: Check the browser console for JavaScript errors
- Confirm attribute names match exactly in all locations
Segmentation Not Working:
- Check if you're using the right data source (built-in vs custom)
- For Stripe metadata, verify values are strings
- For initialization attributes, verify data types match your configuration
- Ensure attribute values are not blank

Can I send Custom Attributes to Churnkey?