# Amplitude — Stripe Projects Integration

## What is Amplitude?

Amplitude is a digital analytics platform that helps teams understand user behavior, ship better products, and grow their business. It provides:

- **Product Analytics** — Track events, build funnels, analyze retention, and understand user journeys
- **Feature Flags** — Roll out features safely with targeted flag delivery
- **Session Replay** — Watch real user sessions to debug issues and understand user experience
- **Experimentation** — Run A/B tests and measure the impact of product changes

## Service Catalog

When you run `stripe projects catalog amplitude`, you'll see two kinds of entries:

- **`amplitude/analytics`** — the deployable resource you actually provision. Provides product analytics, feature flags, session replay, and experimentation. Created with a default Amplitude project under the developer's organization.
- **Plan services** — purchasable tiers that determine quota and billing. The `free` plan is always available; one or more `plus-v3-*` plans are available for paid usage.

Use `stripe projects catalog amplitude --json` to see the exact slugs and pricing exposed to your CLI session.

### Free plan

- Up to 10,000 monthly tracked users (MTU)
- Core analytics, feature flags, and session replay included
- No payment credentials required
- Plan service id: `free`

### Plus plans

- Higher MTU quotas with monthly billing
- Unlimited feature flags, extended session replay, experimentation
- Backed by Stripe Billing — Stripe collects payment via a shared payment token (SPT) at provision time
- Plan service ids follow the pattern `plus-v3-{quota}-mtu-monthly` (e.g., `plus-v3-10k-mtu-monthly`). The exact set of available tiers comes from the live catalog — don't hardcode them
- Annual billing is **not** offered through agentic provisioning; use monthly tiers only

### Selecting a tier when provisioning

The `analytics` deployable accepts a `plan_tier` configuration field:

- Omit it (or set to `"free"`) to provision on the Free plan
- Set to a Plus plan id (e.g. `"plus-v3-10k-mtu-monthly"`) to provision on that paid tier

Example:

```bash
# Free
stripe projects add amplitude/analytics

# Paid — pick a tier from `stripe projects catalog amplitude --json`
stripe projects add amplitude/analytics --config '{"plan_tier":"plus-v3-10k-mtu-monthly"}'
```

The Stripe orchestrator will request payment credentials (an SPT) when a paid tier is selected. Run `stripe projects billing add` first if you don't have a billing method configured.

## Account Configuration

When you first link Amplitude as a provider, Stripe collects two fields defined by Amplitude's account configuration schema:

- **`region`** (required) — `us` or `eu`. Determines the data center where your data is stored and processed. **Cannot be changed after the account is created.**
- **`marketing`** (optional) — boolean opt-in for product updates and marketing communications.

## Key Concepts

### Organizations

An Amplitude organization is the top-level container for all data and settings. Each organization has:

- A unique URL slug (e.g., `my-company`)
- One or more projects
- A billing plan (Free or Plus)

Provisioning creates a new organization under the developer's email if one doesn't already exist, or links to the existing organization for that email.

### Projects

A project is a data container within an organization, typically representing a product or environment. Each project has:

- An **API key** — used to send event data to Amplitude via the SDKs
- A name and description

When you provision the `analytics` resource, a default project is automatically created inside the org.

### `access_configuration` returned by provisioning

After a successful provision (and on credential rotation), Stripe stores an `access_configuration` object containing:

- **`api_key`** — the API key for the default project. Use this to initialize an Amplitude SDK and start sending events.
- **`dashboard_url`** — a URL to the org's analytics dashboard (returned for paid plans).

If the developer needs an API key for a non-default project, they must retrieve it from the Amplitude dashboard under **Settings → Projects**. Use `stripe projects open amplitude` (or the deep link below) to launch an authenticated dashboard session.

## Getting Started After Provisioning

1. **Install the Amplitude Unified SDK** (recommended):

   ```bash
   npm install @amplitude/unified
   ```

   The Unified SDK includes analytics, session replay, and experiment in a single package. For platform-specific SDKs, see https://amplitude.com/docs/get-started/amplitude-quickstart

2. **Initialize the SDK** with the API key from `access_configuration.api_key`:

   ```javascript
   import { Amplitude } from "@amplitude/unified";
   Amplitude.init("YOUR_API_KEY");
   ```

3. **Track events** to capture user behavior:

   ```javascript
   Amplitude.track("Button Clicked", { button_name: "Sign Up" });
   ```

4. **View your data** in the Amplitude dashboard to build charts, funnels, and cohorts.

## Plan Changes

`stripe projects upgrade` issues a non-destructive `update_service` against the `analytics` resource — your existing project, API key, and event data are preserved across plan changes.

### Upgrades

Upgrading from Free to Plus, or moving to a higher Plus tier, takes effect immediately. Stripe charges a prorated amount for the remainder of the current billing cycle.

### Downgrades

Downgrading to a lower Plus tier is scheduled to take effect at the end of the current billing cycle. The developer keeps their current tier until the cycle ends, then automatically moves to the new tier. This avoids refunds or credits.

### Cancellation

Cancelling a paid plan (`stripe projects remove`) is also scheduled for the end of the current billing cycle. The developer keeps access to their paid features until the period ends, then reverts to the Free plan. Cancellation is not immediate.

### Free plan

The Free plan does not require cancellation. It has no billing and remains active indefinitely.

## Deep Links

The integration supports deep links to open the Amplitude dashboard directly from the CLI. The supported `purpose` is `dashboard`, which opens the org's main analytics view as an already-authenticated session.

```bash
stripe projects open amplitude
```

Deep link URLs are short-lived (≈15 minutes) and single-use.

## Data Residency

Amplitude supports both US and EU data centers. The region is selected during account creation (`region` in the account configuration) and cannot be changed afterward — all data is stored and processed in the selected region for the lifetime of the account.

## Support

- Documentation: https://amplitude.com/docs
- Help Center: https://help.amplitude.com/
- Status: https://status.amplitude.com/