Get Customer Analytics Growth

Server URLloading...

GET

/api/v1/external/analytics/customers/growth

Send

Authorization

Header

Query

Reports how the authenticated creator’s customer base moved over a window you choose: how many subscriptions arrived and how that compares with the preceding window, how many of them were paid, how many subscriptions expired versus took a repeat payment, and how instalment plans performed.

Use this to build a growth card or a periodic report. It answers "how is this creator's customer base changing?" — for "what does it look like right now?", use Get Customer Analytics Summary instead. This operation returns aggregates only; it never exposes an individual customer, subscription or payment.

Choosing the window. startDate and endDate are both required and have no default — there is no implicit "last 7 days". Both are absolute ISO 8601 instants, so convert your local day boundaries yourself. endDate must be on or after startDate and at most 90 days after it; for a longer report, call this operation once per 90-day slice. Equal timestamps and future windows are accepted rather than rejected. For equal timestamps, the half-open metrics are empty while the inclusive metrics can count records at that exact instant. A future window can contain scheduled expiry or instalment due dates, so it is not guaranteed to return only zeros.

The comparison window. previousCount and growthPercentage compare your window against the window of identical duration ending exactly where yours begins — ask for the 14 days from 2026-08-01 to 2026-08-15 and the baseline is the 14 days from 2026-07-18 to 2026-08-01. The shift is by elapsed time, not by calendar unit, so a one-month window is compared against the same number of days rather than against the previous calendar month. You never choose the baseline directly; move or resize your own window instead. renewals and flexipay carry no baseline at all — they are single-window measures.

Window edges differ per metric. These figures were built for separate parts of the creator dashboard and each keeps its own boundary rule, so an event landing exactly on endDate is counted by some fields and not others. Every field states its own rule; the safest habit is to send a boundary nothing lands on, such as midnight at the start of the day after the last day you want.

What counts as new. newSubscriptions is deliberately broad: it counts every subscription record created in the window, including free sign-ups and subscriptions that never completed payment, and a customer buying two products counts twice. Use it to size the top of the funnel, and use newPaidSubscriptions for arrivals that carry a price. The paid metric applies stricter filters, but it includes records at exactly endDate while newSubscriptions does not, so its count is not guaranteed to be a numeric subset at that boundary.

Renewals are two separate measures. due counts subscriptions expiring in the window, in any state. renewed counts currently-active subscriptions that took a repeat payment in the window. They are filtered differently and neither is a subset of the other, so a subscription can appear in one and not the other. Do not divide one by the other to get a renewal rate — it is not one. renewed is also indicative rather than exact: for a subscription with several payments, the payment used to place it in the window is not guaranteed to be its most recent one.

Flexipay counts subscriptions. subscriptionsDue and subscriptionsPaid count subscriptions, not individual instalments: a subscription with three instalments due in the window contributes one to each figure it qualifies for. subscriptionsPaid is always less than or equal to subscriptionsDue.

Freshness. Analytics are served from TagMango’s reporting store rather than the live transactional one, so a subscription or payment recorded moments ago may not be reflected yet, and no staleness bound is guaranteed. The four metrics are also read separately rather than from one atomic snapshot, so a change made mid-request can leave them marginally out of step.

Rejected date pairs. A missing, unparseable, out-of-order, or over-90-day pair is rejected before any data is read, and every failing rule is reported at once rather than one at a time. The body carries the failures as a list of messages such as "Start date is required" or "endDate must be on or after startDate and within 90 days".

Query Parameters

Header Parameters

Response Body

curl -X GET "https://api-prod-new.tagmango.com/api/v1/external/analytics/customers/growth?startDate=2026-08-01T00%3A00%3A00.000Z&endDate=2026-08-15T00%3A00%3A00.000Z" \  -H "x-whitelabel-host: string"

{
  "newSubscriptions": {
    "count": 148,
    "previousCount": 121,
    "growthPercentage": 22.3
  },
  "newPaidSubscriptions": {
    "count": 148,
    "previousCount": 121,
    "growthPercentage": 22.3
  },
  "renewals": {
    "due": 64,
    "renewed": 41
  },
  "flexipay": {
    "subscriptionsDue": 12,
    "subscriptionsPaid": 9
  }
}

{
  "code": 400,
  "type": "Bad Request",
  "statusMessage": "BAD_REQUEST",
  "success": false,
  "message": "Invalid request",
  "result": "Invalid request"
}

{
  "code": 401,
  "type": "Unauthorized",
  "statusMessage": "UNAUTHORIZED",
  "message": "Invalid token",
  "result": "Invalid token",
  "success": false
}

{
  "code": 403,
  "type": "Forbidden",
  "statusMessage": "FORBIDDEN",
  "errorCode": "WORKSHOP_MANGO_FORBIDDEN",
  "message": "You can not access this api with a TagMango account, only available for whitelabel hosts",
  "result": "You can not access this api with a TagMango account, only available for whitelabel hosts",
  "success": false
}

{
  "code": 429,
  "type": "Too Many Requests",
  "statusMessage": "TOO_MANY_REQUESTS",
  "message": "Request limit exceeded. try after 10 seconds",
  "result": "Request limit exceeded. try after 10 seconds",
  "success": false
}