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

# Migration: Measurements → Nutzungsmetriken

> Deprecation der Measurement-Endpunkte und Properties zugunsten der neuen Nutzungsmetriken

<Note>
  **Geplante Änderung** - Die Measurement-API und das `measurement` Property werden schrittweise durch das neue Nutzungsmetriken-System ersetzt.
</Note>

## Übersicht

Mit der Einführung der neuen **Nutzungsmetriken** wird das bisherige Measurement-System schrittweise abgelöst. Diese Seite beschreibt die Änderungen und wie du deine Integration anpassen kannst.

### Migrationspfad

| Phase       | Zeitraum | Änderung                                                                    |
| ----------- | -------- | --------------------------------------------------------------------------- |
| **Phase 1** | Aktuell  | Neues Nutzungsmetriken-System verfügbar, Measurements weiterhin unterstützt |
| **Phase 2** | Q1 2026  | `unit` Property wird neben `measurement` hinzugefügt                        |
| **Phase 3** | Q2 2026  | `measurement` Property wird deprecated (Warnung in Response)                |
| **Phase 4** | Q3 2026  | `measurement` Property wird entfernt, nur noch `unit`                       |

***

## Betroffene API Responses

Das `measurement` Property wird aktuell in folgenden API Responses zurückgegeben:

### Product Responses

**Endpunkte:**

* `GET /catalogue/products`
* `GET /catalogue/products/{id}`
* `POST /catalogue/products`
* `PUT /catalogue/products/{id}`

**Aktuelle Struktur:**

```json theme={null}
{
  "id": "prod_abc123",
  "name": "API Calls",
  "measurement": {
    "id": "meas_xyz789",
    "code": "api_calls",
    "description": "Anzahl der API-Aufrufe",
    "aggregationType": "count",
    "type": "metered",
    "fairBilling": true,
    "unit": {
      "id": "unit_123",
      "name": "Stück"
    }
  }
}
```

**Zukünftige Struktur (Phase 2):**

```json theme={null}
{
  "id": "prod_abc123",
  "name": "API Calls",
  "measurement": { ... },  // Bleibt zunächst erhalten
  "unit": {                // NEU: Zusätzlich auf Top-Level
    "id": "unit_123",
    "name": "Stück"
  }
}
```

**Finale Struktur (Phase 4):**

```json theme={null}
{
  "id": "prod_abc123",
  "name": "API Calls",
  "unit": {
    "id": "unit_123",
    "name": "Stück"
  }
}
```

### Plan Responses (PlanResource)

**Endpunkte:**

* `GET /catalogue/plans`
* `GET /catalogue/plans/{id}`
* `POST /catalogue/plans`
* `PUT /catalogue/plans/{id}`

**Betroffen:** `measurement` Property im Plan-Objekt

### SubscriptionItem Responses

**Endpunkte:**

* `GET /subscription-items/{id}`
* `PATCH /subscription-items/{id}`

**Betroffen:** Nested `measurement` in Detail-Responses

### MeasurementValue Responses (Subscription Measurements)

**Endpunkte:**

* `GET /subscription-measurements/{id}`
* `POST /subscription-measurements`
* `POST /subscription-measurements/batch`

**Aktuelle Struktur:**

```json theme={null}
{
  "id": "mv_abc123",
  "measurement": {
    "id": "meas_xyz789",
    "code": "api_calls",
    "unit": {
      "id": "unit_123",
      "name": "Stück"
    }
  },
  "quantity": "150",
  "measuredAt": "2026-01-15T10:00:00Z"
}
```

***

## Deprecated Endpoints

<Warning>
  Die folgenden Endpunkte werden **Q3 2026** entfernt.
</Warning>

### Measurement CRUD Endpoints

| Endpoint                       | Method | Status         |
| ------------------------------ | ------ | -------------- |
| `/catalogue/measurements`      | GET    | **Deprecated** |
| `/catalogue/measurements`      | POST   | **Deprecated** |
| `/catalogue/measurements/{id}` | GET    | **Deprecated** |
| `/catalogue/measurements/{id}` | PUT    | **Deprecated** |
| `/catalogue/measurements/{id}` | DELETE | **Deprecated** |

**Ersatz:** Nutzungsmetrik direkt am Produkt konfigurieren.

### Subscription Measurement Endpoints

| Endpoint                           | Method | Status         | Ersatz                          |
| ---------------------------------- | ------ | -------------- | ------------------------------- |
| `/subscription-measurements`       | POST   | **Deprecated** | `POST /api/usage-events`        |
| `/subscription-measurements/batch` | POST   | **Deprecated** | `POST /api/usage-events`        |
| `/subscription-measurements/{id}`  | GET    | **Deprecated** | Usage über Subscription abrufen |

***

## SubscriptionItem Response Änderungen

### `currentMeasurementValue` wird ersetzt

<Warning>
  Das Property `currentMeasurementValue` wird deprecated und **Q3 2026** durch neue Properties ersetzt.
</Warning>

**Aktuelle Response:**

```json theme={null}
{
  "id": "item_abc123",
  "product": { ... },
  "currentMeasurementValue": {
    "id": "mv_xyz",
    "quantity": "150",
    "measuredAt": "2026-01-15T10:00:00Z"
  }
}
```

**Zukünftige Response:**

Für **Produkte mit fester Menge** (nicht nutzungsbasiert):

```json theme={null}
{
  "id": "item_abc123",
  "product": { ... },
  "quantity": "5",
  "unit": {
    "id": "unit_123",
    "name": "Benutzer"
  }
}
```

Für **nutzungsbasierte Produkte**:

```json theme={null}
{
  "id": "item_abc123",
  "product": { ... },
  "quantity": null,
  "unit": {
    "id": "unit_123",
    "name": "API Calls"
  },
  "currentUsage": {
    "aggregatedValue": "1.523",
    "eventsCount": 47,
    "periodStart": "2026-01-01T00:00:00Z",
    "periodEnd": "2026-02-01T00:00:00Z"
  }
}
```

### Neue Properties

| Property       | Typ            | Beschreibung                                       |
| -------------- | -------------- | -------------------------------------------------- |
| `quantity`     | string \| null | Feste Menge (null für usage-based Produkte)        |
| `unit`         | object         | Einheit mit `id` und `name`                        |
| `currentUsage` | object \| null | Aggregierte Nutzung (nur für usage-based Produkte) |

### `currentUsage` Struktur

| Property          | Typ      | Beschreibung                                       |
| ----------------- | -------- | -------------------------------------------------- |
| `aggregatedValue` | string   | Der aggregierte Wert (z.B. Summe, Anzahl, Maximum) |
| `eventsCount`     | integer  | Anzahl der Ereignisse im Zeitraum                  |
| `periodStart`     | datetime | Beginn des aktuellen Abrechnungszeitraums          |
| `periodEnd`       | datetime | Ende des aktuellen Abrechnungszeitraums            |

<Tip>
  Für detaillierte Nutzungsdaten mit einzelnen Events verwende `GET /subscriptions/{id}/usage`.
</Tip>

### Manuelle Mengenänderungen werden ignoriert

<Warning>
  **Wichtig für Entwickler:** Produkte mit konfigurierter Nutzungsmetrik ignorieren manuelle Mengenänderungen.
</Warning>

### Aktuelles Verhalten

Bei Produkten mit Nutzungsmetrik wird die manuelle Mengenänderung am Subscription Item **ignoriert** (Legacy-Kompatibilität):

```bash theme={null}
# Wird für usage-based Produkte ignoriert
PATCH /subscription-items/{id}
{
  "quantity": 100
}
```

### Zukünftiges Verhalten (ab Q3 2026)

Ab Q3 2026 wird ein Fehler zurückgegeben:

```json theme={null}
{
  "error": {
    "code": "PRODUCT__QUANTITY_CHANGE_NOT_AVAILABLE_FOR_USAGE_BASED_PRODUCTS",
    "message": "Quantity changes are not available for usage-based products. Use usage events instead."
  }
}
```

### Korrekte Vorgehensweise

Für nutzungsbasierte Produkte muss die Menge über **Nutzungsereignisse** gesteuert werden:

```bash theme={null}
POST /api/usage-events
{
  "events": [{
    "transactionId": "unique-id",
    "eventName": "api_call",
    "timestamp": "2026-02-01T10:00:00Z",
    "customerId": "cust_123",
    "properties": {
      "endpoint": "/api/users"
    }
  }]
}
```

***

## Empfohlene Migration

<Note>
  Aktuell haben **alle Produkte** ein `measurement` (Pflichtfeld). Mit dem neuen System wird `measurement` komplett entfernt und durch `unit` ersetzt. Die Konfiguration der Nutzungsmetrik (Event-Name, Aggregation, Filter) erfolgt dann direkt am Produkt über "Nutzungsbasierte Abrechnung aktivieren".
</Note>

### Für API-Konsumenten

**Schritt 1:** Bereite deinen Code vor, das `unit` Property zu verwenden

```javascript theme={null}
// ❌ Bisher
const unitName = product.measurement?.unit?.name;

// ✅ Zukünftig (abwärtskompatibel)
const unitName = product.unit?.name ?? product.measurement?.unit?.name;
```

**Schritt 2:** Stelle Event-Ingestion um

```javascript theme={null}
// ❌ Bisher (deprecated)
await api.post('/subscription-measurements/batch', {
  values: [{
    subscription: 'sub_123',
    subscriptionItem: 'item_456',
    measurementCode: 'api_calls',
    quantity: '1',
    measuredAt: '2026-02-01T10:00:00Z'
  }]
});

// ✅ Neu
await api.post('/api/usage-events', {
  events: [{
    transactionId: 'tx_unique_123',
    eventName: 'api_call',
    timestamp: '2026-02-01T10:00:00Z',
    customerId: 'cust_789',
    properties: {
      endpoint: '/api/users',
      status_code: 200
    }
  }]
});
```

**Schritt 3:** Entferne Quantity-Updates für usage-based Produkte

```javascript theme={null}
// ❌ Nicht mehr verwenden
await api.patch(`/subscription-items/${itemId}`, { quantity: 100 });

// ✅ Mengen werden automatisch aus Events berechnet
```

***

## Zusammenfassung der Änderungen

| Bereich              | Aktuell                         | Zukünftig                |
| -------------------- | ------------------------------- | ------------------------ |
| **Product Response** | `measurement` mit nested `unit` | Nur `unit` (id, name)    |
| **Plan Response**    | `measurement` Property          | `unit` Property          |
| **SubscriptionItem** | `measurement` in Details        | `unit` Property          |
| **Verbrauchsdaten**  | `/subscription-measurements`    | `/api/usage-events`      |
| **Quantity Updates** | Ignoriert (Legacy)              | Fehler für usage-based   |
| **Measurement CRUD** | Eigene Endpoints                | Konfiguration am Produkt |

***

## Fragen?

Bei Fragen zur Migration kontaktiere uns:

* **E-Mail:** [developer@fynn.eu](mailto:developer@fynn.eu)
* **Support:** [support@fynn.eu](mailto:support@fynn.eu)

Oder buche einen [Termin mit unserem Team](https://cal.com/team/fynn/fynn-documentation).