analytics_subscription_billing

Subscription Billing month grid (scheduled, at risk, settled)

Returns one row per date in the requested month — what is scheduled to bill, how much of it is graded at risk, and what already settled — plus the previous month’s totals for the month-over-month figure. Both months come from one service call over a single widened range, so the comparison cannot be assembled from two reads of different data.

Two halves, two sources. Days still to come read commerce_subscriptions.next_bill_date, bucketed in the tz the operator is reading in (echoed back as time_zone). Days that have run read commerce_billing_events, whose local_billed_date is already local.

Money is price * quantity, which is what a renewal charges. Note that the Home > Overview subscription-engine and payment-recovery cards still sum bare price, so they read low against this endpoint for any fleet carrying quantity > 1 until that is corrected.

Renewals are graded at risk by a deterministic read of dunning state — prior declines, hard declines, staleness, whether the retry chain has them in hand. No per-renewal likelihood is served; nothing in the platform produces one.

GET

api

v202604

analytics

subscription_billing

calendar

Subscription Billing month grid (scheduled, at risk, settled)

curl --request GET \
  --url https://api.fluid.app/api/v202604/analytics/subscription_billing/calendar \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.fluid.app/api/v202604/analytics/subscription_billing/calendar"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.fluid.app/api/v202604/analytics/subscription_billing/calendar', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fluid.app/api/v202604/analytics/subscription_billing/calendar",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fluid.app/api/v202604/analytics/subscription_billing/calendar"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.fluid.app/api/v202604/analytics/subscription_billing/calendar")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "month": "2026-09-01",
  "time_zone": "America/Denver",
  "currency": "USD",
  "days": [
    {
      "date": "2026-09-20",
      "scheduled_count": 1,
      "scheduled_amount": "180.25",
      "overdue_count": 1,
      "overdue_amount": "180.25",
      "at_risk_count": 1,
      "at_risk_amount": "180.25",
      "top_risk_driver": "prior_failures",
      "in_flight_count": 1,
      "succeeded_count": 1,
      "succeeded_amount": "180.25",
      "hard_decline_count": 1,
      "hard_decline_amount": "180.25",
      "soft_decline_count": 1,
      "soft_decline_amount": "180.25",
      "awaiting_retry_count": 1,
      "awaiting_retry_amount": "180.25"
    }
  ],
  "totals": {
    "scheduled_count": 1,
    "scheduled_amount": "180.25",
    "overdue_count": 1,
    "overdue_amount": "180.25",
    "renewal_count": 1,
    "renewal_amount": "180.25",
    "succeeded_count": 1,
    "succeeded_amount": "180.25",
    "failed_count": 1,
    "failed_amount": "180.25"
  },
  "previous_totals": {
    "scheduled_count": 1,
    "scheduled_amount": "180.25",
    "overdue_count": 1,
    "overdue_amount": "180.25",
    "renewal_count": 1,
    "renewal_amount": "180.25",
    "succeeded_count": 1,
    "succeeded_amount": "180.25",
    "failed_count": 1,
    "failed_amount": "180.25"
  }
}

{
  "error": {
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "timestamp": "2023-11-07T05:31:56Z",
    "request_id": "<string>"
  }
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "error": "<string>"
}

{
  "error": {
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "timestamp": "2023-11-07T05:31:56Z",
    "request_id": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Bearer token authentication. Requires a company-admin token whose role holds reports.view.

Query Parameters

month

string

Calendar month to report on, as YYYY-MM. Defaults to the current month. A value that is not this exact shape (or names a month that does not exist, such as 2026-13) returns 400 rather than being coerced.

Pattern: ^\d{4}-\d{2}$

Example:

"2026-09"

country

string

ISO alpha-2 code of one of the requesting company's configured countries (see GET /countries). When present, every service on this endpoint filters its data to that country and reports money in the country's own currency. Omit (or send "all") for the aggregate-across-countries view, which is the default and matches pre-Phase-004 behavior. Unknown ISO codes or ones the company is not configured for return 400.

Example:

"US"

string

IANA timezone name (e.g. America/Denver) or Rails-style alias (Eastern Time (US & Canada)) used to anchor "today" boundaries and hour-of-day bucketing. The frontend sends Intl.DateTimeFormat().resolvedOptions().timeZone. Unknown or malformed values silently fall back to UTC — callers omit the param when the endpoint doesn't need wall-clock alignment (see CURRENT-3077).

Example:

"America/Denver"

Response

Month grid payload

month

string<date>

required

First of the month reported.

Example:

"2026-09-01"

time_zone

string

required

IANA zone the scheduled half was bucketed in — the tz that was sent, or UTC when it was missing or unknown. Echoed so the grid can label which day boundaries it is drawing. The settled half needs no such note: billing events carry an already-local date.

Example:

"America/Denver"

currency

string

required

ISO 4217 three-letter code (uppercase).

Required string length: 3

Example:

"USD"

days

object[]

required

One entry per date in the month, ascending, always the full month. A quiet month returns zero-filled days rather than an empty array, so the grid can tell "nothing happened" from "nothing loaded".

Show child attributes

totals

object

required

Month-level sums. renewal_* rolls scheduled and overdue together; the two questions differ, and a previous month is always read after its own overdue floor has passed, so a month-over-month comparison against scheduled_* alone would show nothing there.

Show child attributes

previous_totals

object

required

Show child attributes

Subscription Billing month grid (scheduled, at risk, settled)

curl --request GET \
  --url https://api.fluid.app/api/v202604/analytics/subscription_billing/calendar \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.fluid.app/api/v202604/analytics/subscription_billing/calendar"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.fluid.app/api/v202604/analytics/subscription_billing/calendar', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.fluid.app/api/v202604/analytics/subscription_billing/calendar",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fluid.app/api/v202604/analytics/subscription_billing/calendar"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.fluid.app/api/v202604/analytics/subscription_billing/calendar")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "month": "2026-09-01",
  "time_zone": "America/Denver",
  "currency": "USD",
  "days": [
    {
      "date": "2026-09-20",
      "scheduled_count": 1,
      "scheduled_amount": "180.25",
      "overdue_count": 1,
      "overdue_amount": "180.25",
      "at_risk_count": 1,
      "at_risk_amount": "180.25",
      "top_risk_driver": "prior_failures",
      "in_flight_count": 1,
      "succeeded_count": 1,
      "succeeded_amount": "180.25",
      "hard_decline_count": 1,
      "hard_decline_amount": "180.25",
      "soft_decline_count": 1,
      "soft_decline_amount": "180.25",
      "awaiting_retry_count": 1,
      "awaiting_retry_amount": "180.25"
    }
  ],
  "totals": {
    "scheduled_count": 1,
    "scheduled_amount": "180.25",
    "overdue_count": 1,
    "overdue_amount": "180.25",
    "renewal_count": 1,
    "renewal_amount": "180.25",
    "succeeded_count": 1,
    "succeeded_amount": "180.25",
    "failed_count": 1,
    "failed_amount": "180.25"
  },
  "previous_totals": {
    "scheduled_count": 1,
    "scheduled_amount": "180.25",
    "overdue_count": 1,
    "overdue_amount": "180.25",
    "renewal_count": 1,
    "renewal_amount": "180.25",
    "succeeded_count": 1,
    "succeeded_amount": "180.25",
    "failed_count": 1,
    "failed_amount": "180.25"
  }
}

{
  "error": {
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "timestamp": "2023-11-07T05:31:56Z",
    "request_id": "<string>"
  }
}

{
  "message": "<string>"
}

{
  "message": "<string>",
  "error": "<string>"
}

{
  "error": {
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "timestamp": "2023-11-07T05:31:56Z",
    "request_id": "<string>"
  }
}

Overview

Task guides

Portal & Widgets

Endpoints

Auth endpoints

Checkout endpoints

Public SDK endpoints

Member endpoints

Payment gateway endpoints

Cart payment endpoints

Commerce endpoints

Webhooks endpoints

Company admin endpoints (v0)

Analytics

Subscription Billing month grid (scheduled, at risk, settled)

Authorizations

Query Parameters

Response