SaaSFlow
DevelopersAPIReferencesubscription_events

Create subscription event

Record a subscription event, which is how revenue actually enters SaaSFlow. `mrrChange` is a signed delta in the subscription's currency, sent as a decimal string so nothing is lost to floating point: positive for a new subscription or an upgrade, negative for a downgrade, and the negative of everything booked so far for a full cancellation. `quantityChange` is the matching seat or unit delta. `effectiveTime` is when the change hits MRR and `committedTime` is when it was agreed, and getting the two the wrong way round is the usual cause of MRR landing in the wrong month. Fails with 404 if the subscription is not in this company.

Authentication

You're not signed in. Either sign in at app.saasflow.com and reload (then pick sessionCookie), or paste a SaaSFlow sf_… API key in the bearerAuth field below.
POST
/companies/{companyId}/subscription_events

Authorization

Authorization<token>

A SaaSFlow API key (format sf_…) or an OAuth bearer token. Paste only the key — the proxy adds the Bearer prefix. Create an API key in Settings → Company settings → API keys — see API keys.

In: header

Path Parameters

companyId*string
Length1 <= length

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/companies/string/subscription_events" \  -H "Content-Type: application/json" \  -d '{    "subscriptionId": "string",    "productId": "string",    "committedTime": "string",    "effectiveTime": "string",    "mrrChange": "string",    "quantityChange": 0,    "billingInterval": "string",    "billingIntervalCount": 0  }'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda",  "subscriptionId": "d079718b-ff63-45dd-947b-4950c023750f",  "productId": "dcd53ddb-8104-4e48-8cc0-5df1088c6113",  "committedTime": "2019-08-24T14:15:22Z",  "effectiveTime": "2019-08-24T14:15:22Z",  "mrrChange": "string",  "quantityChange": -8388608,  "billingInterval": "day",  "billingIntervalCount": -2147483648,  "createdTime": "2019-08-24T14:15:22Z",  "createdUserId": "string",  "lastUpdatedTime": "2019-08-24T14:15:22Z",  "lastUpdatedUserId": "string"}

List subscription events

List subscription events, optionally narrowed by `subscriptionId` or `customerId`. These events are the ledger SaaSFlow computes MRR from. Each row is a **delta**, not a level: `mrrChange` is the amount added or removed at that moment, so a subscription's current MRR is the sum of its events, and a plain cancellation shows up as a negative `mrrChange` that offsets what came before. Two timestamps matter and they are not interchangeable: `effectiveTime` is when the change hits MRR, `committedTime` is when it was agreed, which is what committed MRR is measured on. Amounts are in the parent subscription's currency.

Delete subscription event

Delete a subscription event. Its `mrrChange` is removed from every period after its `effectiveTime`, so deleting the wrong row leaves a subscription permanently over- or under-counted. To end a subscription, add a cancelling event rather than deleting the ones that created it.