> ## Documentation Index
> Fetch the complete documentation index at: https://help.statisfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Product Usage Import

> Track product usage metrics by importing data from CSV files.

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. The snapshot period is configured on the product in **Admin > Settings > Object Manager > Products**:

| Period    | Description       | Auto-Calculated Date      |
| --------- | ----------------- | ------------------------- |
| Single    | One-time snapshot | Current date              |
| Daily     | Daily metrics     | Previous day              |
| Weekly    | Weekly metrics    | Previous Monday           |
| Monthly   | Monthly metrics   | First of previous month   |
| Quarterly | Quarterly metrics | First of previous quarter |
| Yearly    | Annual metrics    | First of previous year    |

<Note>
  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.
</Note>

### Configure Usage Import

During CSV Import setup (Step 5):

1. **Select or Create a Product**
   * Choose an existing product from the dropdown
   * Or click **Create New** to add a product

2. **Snapshot Period** (read-only)
   * The snapshot period is configured on the product itself (in **Admin > Settings > Object Manager > Products**)
   * It cannot be changed during CSV import setup — this ensures all integrations for a product use the same period
   * If the product has no snapshot period set, you'll be directed to configure it in product settings first

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`)

   <Tip>
     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.
   </Tip>

4. **Map Dimensions**

   For each metric you want to track:

   a. Click **Add Metric**

   b. Select the **CSV Column** containing the data

   c. Select or create a **Dimension**:

   * Choose existing dimension, or
   * Create new with name and data type

   d. Set the **Data Type**:

   * **Numeric**: Numbers (integers, decimals)
   * **Text**: String values
   * **Boolean**: True/false values

### Example Configuration

**CSV File:**

```csv theme={null}
customer_id,mau,api_calls,plan_type,is_active
CUST001,500,25000,Enterprise,true
CUST002,150,8000,Professional,true
CUST003,25,1200,Starter,false
```

**Mappings:**

| CSV Column | Dimension            | Data Type |
| ---------- | -------------------- | --------- |
| mau        | Monthly Active Users | Numeric   |
| api\_calls | API Request Count    | Numeric   |
| plan\_type | Subscription Plan    | Text      |
| is\_active | Active Status        | Boolean   |

### Creating Dimensions

When creating a new dimension during import setup:

1. Enter a descriptive name (e.g., "Monthly Active Users")
2. Select the data type:
   * **Numeric** for counts, amounts, scores
   * **Text** for categories, tiers, labels
   * **Boolean** for yes/no, true/false values
3. The dimension is created and available for future imports

<Tip>
  Use consistent dimension names across imports. "MAU" and "Monthly Active Users" would create two different dimensions.
</Tip>

### 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

You can track usage for multiple products in a single CSV import:

1. Create separate dimension mappings for each product
2. Or set up multiple CSV Import integrations (one per product)

### Best Practices

<Accordion title="Choose appropriate snapshot periods">
  Match the period to how often you collect data. Snapshot periods are configured on the product in the Object Manager:

  * **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.
</Accordion>

<Accordion title="Use consistent identifiers">
  Always include a reliable account identifier:

  * CRM ID is most reliable
  * Domain works well for most cases
  * Avoid account names if possible
</Accordion>

<Accordion title="Validate data types">
  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
</Accordion>

<Accordion title="Handle missing data">
  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
</Accordion>

### Troubleshooting

<Accordion title="Usage not appearing on accounts">
  * Verify the account was matched (check test results)
  * Confirm the dimension was created successfully
  * Check that the data type matches the CSV values
</Accordion>

<Accordion title="Incorrect date assignment">
  * Review the snapshot period on the product (**Admin > Settings > Object Manager > Products**)
  * 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)
</Accordion>

<Accordion title="Duplicate records">
  * 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
</Accordion>