Skip to main content
Product usage metrics help you understand how customers use your product. CSV Import lets you track usage dimensions like Monthly Active Users, API calls, storage consumption, and more.

​
Understanding Product Usage

Products represent what you sell or provide to customers (e.g., “Platform”, “Enterprise Plan”). Dimensions are the specific metrics you track for each product:
  • Monthly Active Users (MAU)
  • API Request Count
  • Storage Used (GB)
  • Feature Adoption Score
  • Login Frequency
Snapshot Periods define how often data is captured. You set the snapshot period at the top of Step 5 in the CSV integration wizard; it applies to the whole integration, across every product it feeds:
If your CSV includes a date column, the date from each row is used instead of the auto-calculated date. The date is snapped to the nearest period boundary.

​
Configure Usage Import

During CSV Import setup (Step 5):
  1. Snapshot Period
    • Choose how often data is captured (Single, Daily, Weekly, Monthly, Quarterly, or Yearly)
    • The period is an integration-level setting: every metric the integration records, across all products, uses the same period
    • If a mapped product’s own usage widget is configured for a different period, the wizard shows an inline warning — usage written at the integration’s period will not appear on that product’s widget
  2. Week Start Day (Weekly snapshot periods only)
    • Choose which day your reporting week begins on. Defaults to Monday.
    • Weekly snapshots are stamped with the start of the previous week. With Monday selected, a run on Saturday 15 Nov 2025 records 2025-11-03; with Wednesday selected, the same run records 2025-11-05.
    • This also applies when a date column is used — each row’s date is snapped back to the most recent occurrence of the day you pick.
    Changing the Week Start Day only affects data imported afterwards; existing rows are not re-dated. Because a product usage row is identified partly by its date, re-importing an old file after a change writes a new row at the shifted date instead of updating the original.
  3. Date Column (optional)
    • By default, dates are auto-calculated based on the snapshot period (e.g., first of previous month for Monthly)
    • You can optionally select a CSV column that contains the date for each row
    • When a date column is used, dates are read from the CSV and snapped to the appropriate period boundary (e.g., 2024-10-15 with a Monthly period becomes 2024-10-01)
    The date column is useful for backfilling historical product usage data. For example, if you have 12 months of usage data in a single CSV, include a date column so each row gets assigned to the correct month.
  4. Map Dimensions For each metric you want to track: a. Click Add Metric b. Select the CSV Column containing the data c. Select the Usage Dimension. The picker lists every dimension in your workspace, each showing the product it belongs to and its key. Choosing a dimension settles both the product and the data type for the row — you don’t select them separately. Rows are grouped by product in collapsible sections, and rows without a dimension yet appear under Unassigned. A dimension already mapped in another row is hidden from the picker, so each dimension can only be mapped once per integration.

​
Example Configuration

CSV File:
Mappings:

​
Creating Dimensions

When creating a new dimension during import setup:
  1. Pick the product the dimension belongs to in the Product for new dimension selector, then click New Dimension
  2. Enter a descriptive name (e.g., “Monthly Active Users”)
  3. Select the data type:
    • Numeric for counts, amounts, scores
    • Text for categories, tiers, labels
    • Boolean for yes/no, true/false values
  4. The dimension is created and available for future imports
Use consistent dimension names across imports. “MAU” and “Monthly Active Users” would create two different dimensions.

​
Viewing Usage Data

After import, product usage data appears on:
  • Account Pages: Usage metrics in the account details
  • Reports: Analyze usage trends across customers
  • Segments: Filter accounts by usage criteria

​
Multiple Products

A single CSV integration can feed multiple products. Because each dimension belongs to a product, just map columns to dimensions from different products — the wizard groups the mapping rows by product so you can see what each product receives. Keep in mind that the snapshot period is shared across the whole integration. If your products capture usage at different periods, set up a separate integration per period.

​
Best Practices

Match the period to how often you collect data. The snapshot period is set on the integration in Step 5:
  • Daily: For real-time or daily metrics
  • Weekly: For weekly summaries
  • Monthly: For monthly business metrics
  • Quarterly/Yearly: For periodic business reviews
Use the date column option if you need to backfill historical data across multiple periods in a single CSV file.
Always include a reliable account identifier:
  • CRM ID is most reliable
  • Domain works well for most cases
  • Avoid account names if possible
Ensure CSV data matches dimension types:
  • Numeric dimensions need numbers (not “N/A” or blank)
  • Boolean dimensions need true/false values
  • Text dimensions accept any string
For rows with missing usage data:
  • Leave cells blank (not zero, unless zero is meaningful)
  • Blank values are skipped during import
  • Zero values are recorded as actual zero usage

​
Troubleshooting

  • Verify the account was matched (check test results)
  • Confirm the dimension was created successfully
  • Check that the data type matches the CSV values
  • Check that the integration’s snapshot period matches the period the product’s usage widget expects — data written at a different period won’t appear on the widget (the wizard warns about this in Step 5)
  • Review the integration’s snapshot period (Step 5 of the wizard)
  • Monthly period uses first of previous month when auto-calculating
  • If using a date column, verify the CSV dates are in a parseable format and the column is correctly selected
  • Dates from a date column are snapped to period boundaries (e.g., any date in October with Monthly period becomes October 1st)
  • Check if “Allow Multiple Rows Per Customer” is enabled
  • If disabled, latest values overwrite previous ones
  • Use this setting based on whether you want history or latest only