Zum Hauptinhalt springen
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

PhaseZeitraumÄnderung
Phase 1AktuellNeues Nutzungsmetriken-System verfügbar, Measurements weiterhin unterstützt
Phase 2Q1 2026unit Property wird neben measurement hinzugefügt
Phase 3Q2 2026measurement Property wird deprecated (Warnung in Response)
Phase 4Q3 2026measurement 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

EndpointMethodStatus
/catalogue/measurementsGETDeprecated
/catalogue/measurementsPOSTDeprecated
/catalogue/measurements/{id}GETDeprecated
/catalogue/measurements/{id}PUTDeprecated
/catalogue/measurements/{id}DELETEDeprecated
Ersatz: Nutzungsmetrik direkt am Produkt konfigurieren.

​
Subscription Measurement Endpoints

EndpointMethodStatusErsatz
/subscription-measurementsPOSTDeprecatedPOST /api/usage-events
/subscription-measurements/batchPOSTDeprecatedPOST /api/usage-events
/subscription-measurements/{id}GETDeprecatedUsage ü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

PropertyTypBeschreibung
quantitystring | nullFeste Menge (null für usage-based Produkte)
unitobjectEinheit mit id und name
currentUsageobject | nullAggregierte Nutzung (nur für usage-based Produkte)

​
currentUsage Struktur

PropertyTypBeschreibung
aggregatedValuestringDer aggregierte Wert (z.B. Summe, Anzahl, Maximum)
eventsCountintegerAnzahl der Ereignisse im Zeitraum
periodStartdatetimeBeginn des aktuellen Abrechnungszeitraums
periodEnddatetimeEnde 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

BereichAktuellZukünftig
Product Responsemeasurement mit nested unitNur unit (id, name)
Plan Responsemeasurement Propertyunit Property
SubscriptionItemmeasurement in Detailsunit Property
Verbrauchsdaten/subscription-measurements/api/usage-events
Quantity UpdatesIgnoriert (Legacy)Fehler für usage-based
Measurement CRUDEigene EndpointsKonfiguration am Produkt

​
Fragen?

Bei Fragen zur Migration kontaktiere uns: Oder buche einen Termin mit unserem Team.