Migration: Measurements → Nutzungsmetriken

Geplante Änderung - Die Measurement-API und das measurement Property werden schrittweise durch das neue Nutzungsmetriken-System ersetzt.

Ü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:

{
  "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):

{
  "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):

{
  "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:

{
  "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

Die folgenden Endpunkte werden Q3 2026 entfernt.

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

Das Property currentMeasurementValue wird deprecated und Q3 2026 durch neue Properties ersetzt.

Aktuelle Response:

{
  "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):

{
  "id": "item_abc123",
  "product": { ... },
  "quantity": "5",
  "unit": {
    "id": "unit_123",
    "name": "Benutzer"
  }
}

Für nutzungsbasierte Produkte:

{
  "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

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

Manuelle Mengenänderungen werden ignoriert

Wichtig für Entwickler: Produkte mit konfigurierter Nutzungsmetrik ignorieren manuelle Mengenänderungen.

Aktuelles Verhalten

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

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

{
  "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:

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

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”.

Für API-Konsumenten

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

// ❌ 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

// ❌ 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

// ❌ 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
Support: support@fynn.eu

Oder buche einen Termin mit unserem Team.

API documentation

User

Tenant

Customer

Catalogue

Subscription

Invoice

Payment

Dunning

Offer

Checkout

Feature & Entitlement

Analytics

Accounting

Settings

Migration: Measurements → Nutzungsmetriken

Übersicht

Migrationspfad

Betroffene API Responses

Product Responses

Plan Responses (PlanResource)

SubscriptionItem Responses

MeasurementValue Responses (Subscription Measurements)

Deprecated Endpoints

Measurement CRUD Endpoints

Subscription Measurement Endpoints

SubscriptionItem Response Änderungen

`currentMeasurementValue` wird ersetzt

Neue Properties

`currentUsage` Struktur

Manuelle Mengenänderungen werden ignoriert

Aktuelles Verhalten

Zukünftiges Verhalten (ab Q3 2026)

Korrekte Vorgehensweise

Empfohlene Migration

Für API-Konsumenten

Zusammenfassung der Änderungen

Fragen?

​Übersicht

​Migrationspfad

​Betroffene API Responses

​Product Responses

​Plan Responses (PlanResource)

​SubscriptionItem Responses

​MeasurementValue Responses (Subscription Measurements)

​Deprecated Endpoints

​Measurement CRUD Endpoints

​Subscription Measurement Endpoints

​SubscriptionItem Response Änderungen

​currentMeasurementValue wird ersetzt

​Neue Properties

​currentUsage Struktur

​Manuelle Mengenänderungen werden ignoriert

​Aktuelles Verhalten

​Zukünftiges Verhalten (ab Q3 2026)

​Korrekte Vorgehensweise

​Empfohlene Migration

​Für API-Konsumenten

​Zusammenfassung der Änderungen

​Fragen?

Übersicht

Migrationspfad

Betroffene API Responses

Product Responses

Plan Responses (PlanResource)

SubscriptionItem Responses

MeasurementValue Responses (Subscription Measurements)

Deprecated Endpoints

Measurement CRUD Endpoints

Subscription Measurement Endpoints

SubscriptionItem Response Änderungen

`currentMeasurementValue` wird ersetzt

Neue Properties

`currentUsage` Struktur

Manuelle Mengenänderungen werden ignoriert

Aktuelles Verhalten

Zukünftiges Verhalten (ab Q3 2026)

Korrekte Vorgehensweise

Empfohlene Migration

Für API-Konsumenten

Zusammenfassung der Änderungen

Fragen?