analytics_subscription_billing

Subscription Billing month reporting (reasons, markets, timing)

Returns the requested month’s failure reporting: decline reasons, market splits, timing buckets, and the daily revenue trend.

Reasons are bucketed through the same category list the Home > Overview recovery card uses, and recoverability is Commerce::BillingEvent.retriable_failure? — the predicate the retry cron itself gates on — so nothing is reported as recoverable that the chain would refuse to attempt.

Rates are withheld rather than estimated below a sample floor: a timing bucket reports sufficient_sample: false and a null rate, and a thin market reports a null top_decline_reason.

Cohort retention is deliberately absent. It has no source in the platform today and is tracked as its own phase.

GET

api

v202604

analytics

subscription_billing

breakdown

Subscription Billing month reporting (reasons, markets, timing)

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

import requests

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

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/breakdown', 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/breakdown",
  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/breakdown"

	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/breakdown")

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",
  "currency": "USD",
  "resolved_count": 1,
  "succeeded_count": 1,
  "failure_count": 1,
  "failure_rate": "42.5",
  "recoverable_amount": "180.25",
  "lost_amount": "180.25",
  "daily_trend": [
    {
      "date": "2026-09-20",
      "revenue": "180.25"
    }
  ],
  "decline_reasons": [
    {
      "label": "insufficient funds",
      "count": 1,
      "amount": "180.25",
      "recoverable_count": 1,
      "recoverable_amount": "180.25",
      "share_of_failures": "42.5"
    }
  ],
  "markets": [
    {
      "country_iso": "US",
      "country_name": "United States",
      "resolved_count": 1,
      "amount": "180.25",
      "failure_count": 1,
      "failure_rate": "42.5",
      "top_decline_reason": "insufficient funds"
    }
  ],
  "hour_bands": [
    {
      "label": "12:00-17:59",
      "resolved_count": 1,
      "success_rate": "42.5",
      "sufficient_sample": true
    }
  ],
  "month_parts": [
    {
      "label": "12:00-17:59",
      "resolved_count": 1,
      "success_rate": "42.5",
      "sufficient_sample": true
    }
  ]
}

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

Response

Month reporting payload

month

string<date>

required

Example:

"2026-09-01"

currency

string

required

ISO 4217 three-letter code (uppercase).

Required string length: 3

Example:

"USD"

resolved_count

integer

required

Charges that ran and reached an outcome. Staged and attempted events are excluded — they have no outcome yet, and counting them would deflate every rate here.

Required range: x >= 0

succeeded_count

integer

required

Required range: x >= 0

failure_count

integer

required

Required range: x >= 0

failure_rate

string

required

A percentage share, expressed as a decimal string rounded to one decimal place. "100.0" when a single bucket accounts for the full total; "0.0" when the divisor was zero.

Example:

"42.5"

recoverable_amount

string

required

Decimal amount, expressed as a string to preserve arbitrary precision across the wire. Parsed to Number on the client and formatted with Intl.NumberFormat. Once the in-flight money-cents-migration lands, this will switch to a { amount_cents: integer, currency: string } object.

Example:

"180.25"

lost_amount

string

required

Example:

"180.25"

daily_trend

object[]

required

Cleared money per date, zero-filled across the month.

Show child attributes

decline_reasons

object[]

required

Ordered by count descending.

Show child attributes

markets

object[]

required

Ordered by money descending.

Show child attributes

hour_bands

object[]

required

Four six-hour windows partitioning the day, in UTC. These describe when the billing pipeline ran a charge, which is a property of the platform rather than of the reader — unlike the calendar's scheduled half.

Show child attributes

month_parts

object[]

required

Thirds of the month.

Show child attributes

Subscription Billing month reporting (reasons, markets, timing)

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

import requests

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

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/breakdown', 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/breakdown",
  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/breakdown"

	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/breakdown")

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",
  "currency": "USD",
  "resolved_count": 1,
  "succeeded_count": 1,
  "failure_count": 1,
  "failure_rate": "42.5",
  "recoverable_amount": "180.25",
  "lost_amount": "180.25",
  "daily_trend": [
    {
      "date": "2026-09-20",
      "revenue": "180.25"
    }
  ],
  "decline_reasons": [
    {
      "label": "insufficient funds",
      "count": 1,
      "amount": "180.25",
      "recoverable_count": 1,
      "recoverable_amount": "180.25",
      "share_of_failures": "42.5"
    }
  ],
  "markets": [
    {
      "country_iso": "US",
      "country_name": "United States",
      "resolved_count": 1,
      "amount": "180.25",
      "failure_count": 1,
      "failure_rate": "42.5",
      "top_decline_reason": "insufficient funds"
    }
  ],
  "hour_bands": [
    {
      "label": "12:00-17:59",
      "resolved_count": 1,
      "success_rate": "42.5",
      "sufficient_sample": true
    }
  ],
  "month_parts": [
    {
      "label": "12:00-17:59",
      "resolved_count": 1,
      "success_rate": "42.5",
      "sufficient_sample": true
    }
  ]
}

{
  "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 reporting (reasons, markets, timing)

Authorizations

Query Parameters

Response