Beast Insights
  1. Order Summary Data
Beast Insights
  • Order Summary Data
    • Order Summary (Event Date)
      POST
    • Cohort Summary (Initial Date)
      POST
  • BIN Routing
    • BIN Routing
      POST
  • Schemas
    • Schemas
      • PaginationInfo
      • OrderSummaryRecord
    • Response
      • UnauthorizedError
      • RateLimitError
      • BadRequestError
      • InternalServerError
    • ErrorResponse
    • SuccessResponse
    • BinRoutingRequest
    • OrderSummaryCohortRequest
    • OrderSummaryRequest
    • BinRoutingResponse
  1. Order Summary Data

Cohort Summary (Initial Date)

POST
https://api.beastinsights.com/api/data/cohort
Order Summary Data

Cohort Summary (Initial Date)#

This endpoint retrieves order summary data grouped by initial/trial date - when the customer first signed up. This is essential for cohort analysis and understanding customer lifetime value.

Key Difference from /api/data#

/api/data: Groups by event date (when refund/chargeback occurred)
/api/data/cohort: Groups by initial date (when customer first signed up)

Use Cases#

1. Customer Lifetime Value (LTV)#

Track total revenue, refunds, and chargebacks attributed to customers who signed up on a specific date:
{
  "start_date": "2025-07-01",
  "end_date": "2025-07-30",
  "group_by": ["date"],
  "metrics": ["revenue_by_initial_date", "cb_amount_by_initial_date", "refund_amount_by_initial_date"]
}

2. Cohort Retention Analysis#

Analyze how customers from different sign-up periods perform over time:
{
  "start_date": "2025-07-01",
  "end_date": "2025-07-30",
  "group_by": ["date", "billing_cycle"],
  "metrics": ["approvals_by_initial_date", "revenue_by_initial_date"]
}

3. Campaign ROI by Cohort#

Measure true campaign performance by tracking outcomes back to the initial acquisition:
{
  "start_date": "2025-07-01",
  "end_date": "2025-07-30",
  "group_by": ["campaign_id"],
  "metrics": ["revenue_by_initial_date", "cb_amount_by_initial_date", "cpa"]
}

Available Dimensions#

All dimensions use the trial/initial transaction values:
date (initial date), sales_type, billing_cycle, attempt_col, refund_type, alert_type
price_point, bin, affid, sub_affid, campaign_id, product_id, gateway_id
product_name, product_group, campaign_name, campaign_type
mcc, acquirer, gateway_alias, bank, card_brand, card_type

Available Metrics#

All metrics are attributed to the initial date:
Core: approvals_by_initial_date, attempts_by_initial_date, revenue_by_initial_date, cpa
Chargebacks: cb_count_by_initial_date, cb_amount_by_initial_date
Refunds: refund_count_by_initial_date, refund_amount_by_initial_date
Alerts: alert_count_by_initial_date, alert_by_initial_date
By Sales Type: initial_attempt, initial_approved, rebills_attempted, rebills_approved

Important Notes#

Date Range Limit: Maximum 100 days between start_date and end_date
Response Limit: Maximum 1000 records per request
Rate Limiting: 5 requests per minute per client
Date Meaning: start_date and end_date filter by initial/trial date, not event date

Authentication#

Required headers: x-client-id and x-client-secret

Request

Authorization
Bearer Token
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
or
Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200OK
application/json
Cohort data retrieved successfully
Headers

Body

🟠400Bad Request
🟠401Unauthorized
🟠429RateLimitError
🔴500Server Error
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location --request POST 'https://api.beastinsights.com/api/data/cohort' \
--header 'x-client-id;' \
--header 'x-client-secret;' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "start_date": "2025-07-01",
    "end_date": "2025-07-30"
}'
Response Response Example
200 - LTV data grouped by initial date
{
    "success": true,
    "code": 200,
    "message": "Cohort summary data retrieved successfully (grouped by initial date)",
    "data": [
        {
            "date": "2025-07-01",
            "revenue_by_initial_date": 15248.75,
            "approvals_by_initial_date": 284,
            "cb_amount_by_initial_date": 450,
            "refund_amount_by_initial_date": 1247.5
        },
        {
            "date": "2025-07-02",
            "revenue_by_initial_date": 12847.25,
            "approvals_by_initial_date": 256,
            "cb_amount_by_initial_date": 320,
            "refund_amount_by_initial_date": 892.3
        }
    ],
    "pagination": {
        "total": 30,
        "limit": 100,
        "offset": 0,
        "has_more": false
    },
    "timestamp": "2025-08-05T10:30:00.000Z"
}
Modified at 2025-12-17 12:23:57
Previous
Order Summary (Event Date)
Next
BIN Routing
Built with