GET /management/instances/$INSTANCE/statistics-report/$NAME

GET [/instances/$INSTANCE]/private/statistics-report/$NAME

This request will return be used to generate a specific report based on $NAME. The backend MAY support generating the report in various formats. Supported values for $NAME include:

• “transactions” (total revenue, total refunds, fees as well as number of transactions), since v25

• “money-pots” (changes to totals in money pots), since v25

• “taxes” (amount of taxes withheld by tax class), since vTAXES,

• “sales-funnel” (number and volume of orders created, claimed, paid, refunded and settled), since vXXX,

The overall endpoint family exists since protocol v25.

Required permission: statistics-read

Request:

Accept:

The client may specify the desired MIME-type for the result. Supported are the usual “application/json”, but also “application/pdf”.

query granularity:

Optional. Determines the bucket granularity to return. Accepted are “hour”, “day”, “week”, “month”, “quarter” and “year”. Defaults to “month”.

query count:

Optional. Number of buckets to return. Defaults depends on the granularity.

Response:

200 Ok:

If JSON is requested, the body will be a MerchantStatisticsReportResponse, otherwise a PDF.

401 Unauthorized:

The request is unauthorized.

404 Not found:

The instance is unknown to the backend.

410 Gone:

The requested statistical data is unavailable because it is not kept at the requested granularity for this long.

501 Not implemented:

The requested functionality is not implemented. Usually returned if the PDF generator is not available at this backend and the requested format was application/pdf.

Details:

interface MerchantStatisticsReportResponse {

  // Name of the business for which the report is generated.
  business_name: string;

  // Starting date for the report.
  start_date: Timestamp;

  // End date for the report.
  end_date: Timestamp;

  // Period of time covered by each bucket (aka granularity).
  bucket_period: RelativeTime;

  // Charts to include in the report.
  charts: MerchantReportChart[];

}

interface MerchantReportChart {

  // Name of the chart.
  chart_name: string;

  // Label to use for the y-axis of the chart.
  // (x-axis is always time).
  y_label: string;

  // Statistical values for the respective time windows,
  // one entry per bucket_period in between start_date
  // and end_date.
  data_groups: BucketDataGroup[];

  // Human-readable labels for the values in each of the
  // data_groups. Length of the array must match the
  // length of the values arrays.
  labels: string[];

  // Should the values in each of the data_groups
  // be rendered cumulatively or using a grouped representation?
  cumulative: boolean;

}

interface BucketDataGroup {

  // Starting data for this group
  start_date: Timestamp;

  // Values in the data group.
  values: Float[];

}