Create a custom KPI

POST

https://core.shopimind.com/v1/custom-stats/kpis

Creates a custom KPI: measures aggregated hour by hour from a source (system schema or custom data definition) into a dedicated aggregate table, kept up to date by a scheduled event. Field paths must come from listCustomKpiFields. The KPI is returned with status: backfilling while its history (lookback_max_months, 12 by default) is computed asynchronously. Use previewCustomKpi to check a configuration before creating it.

Parameters

Header Parameters

spm-api-key*

[Authentication] Required API key, in the form {prefix}.{secret}.

Type

string

Required

Example"a1b2c3d4.xK9pR2mVn6QwErTyUiOpAsDfGhJkLzXcVbNmQwErTyU"

Pattern

"^[a-zA-Z0-9]{8}\\.[A-Za-z0-9_-]+$"

Request Body

application/json

{

  

"name": {

  

},

  

"description": {

  

},

  

"source_type": "string",

  

"source_schema_name": "orders",

  

"relations_chain": [

  

  

"contacts"

  

],

  

"measures": [

  

  

{

  

  

  

"id_measure": "string",

  

  

  

"type": "string",

  

  

  

"field": "t.amount",

  

  

  

"label": {

  

  

  

},

  

  

  

"format": "number",

  

  

  

"suffix": "string",

  

  

  

"position": 0

  

  

}

  

],

  

"dimensions": [

  

  

{

  

  

  

"id_dimension": "string",

  

  

  

"field": "t.status",

  

  

  

"label": {

  

  

  

},

  

  

  

"position": 0

  

  

}

  

],

  

"time_field": "t.date_creation",

  

"time_field_explicit": true,

  

"filters": [

  

  

{

  

  

  

"field": "t.amount",

  

  

  

"operator": "string",

  

  

  

"value": {

  

  

  

}

  

  

}

  

],

  

"lookback_max_months": 12

}

Responses

Custom KPI created successfully.

Content-Type

application/json

{

  

"statusCode": 201,

  

"data": {

  

  

"id_custom_kpi": "3",

  

  

"id_shop": 1234,

  

  

"name": {

  

  

},

  

  

"description": {

  

  

},

  

  

"source_type": "system",

  

  

"source_schema_name": "orders",

  

  

"source_table_name": "shopyminddata.shops_orders",

  

  

"relations_chain": [

  

  

  

"contacts"

  

  

],

  

  

"filters_json": [

  

  

  

{

  

  

  

  

"field": "t.amount",

  

  

  

  

"operator": "string",

  

  

  

  

"value": {

  

  

  

  

}

  

  

  

}

  

  

],

  

  

"time_field": "t.date_creation",

  

  

"time_field_explicit": true,

  

  

"aggregate_table_name": "kpi_1234_3_agg",

  

  

"aggregate_procedure_name": "kpi_1234_3_aggregate",

  

  

"aggregate_event_name": "kpi_1234_3_event",

  

  

"status": "active",

  

  

"last_event_run_at": "2026-05-04T10:00:00.000Z",

  

  

"last_error": "string",

  

  

"lookback_max_months": 12,

  

  

"id_user_creator": "58",

  

  

"id_user_modifier": "string",

  

  

"created_at": "2026-05-04T09:12:00.000Z",

  

  

"updated_at": "2026-05-04T09:12:00.000Z",

  

  

"measures": [

  

  

  

{

  

  

  

  

"id_measure": "12",

  

  

  

  

"id_custom_kpi": "3",

  

  

  

  

"type": "sum",

  

  

  

  

"field": "t.amount",

  

  

  

  

"format": "currency",

  

  

  

  

"suffix": "string",

  

  

  

  

"label_json": {

  

  

  

  

},

  

  

  

  

"label": {

  

  

  

  

},

  

  

  

  

"position": 0,

  

  

  

  

"created_at": "2026-05-04T09:12:00.000Z",

  

  

  

  

"updated_at": "2026-05-04T09:12:00.000Z"

  

  

  

}

  

  

],

  

  

"dimensions": [

  

  

  

{

  

  

  

  

"id_dimension": "7",

  

  

  

  

"id_custom_kpi": "3",

  

  

  

  

"field": "t.status",

  

  

  

  

"label_json": {

  

  

  

  

},

  

  

  

  

"label": {

  

  

  

  

},

  

  

  

  

"column_index": 1,

  

  

  

  

"position": 0,

  

  

  

  

"created_at": "2026-05-04T09:12:00.000Z",

  

  

  

  

"updated_at": "2026-05-04T09:12:00.000Z"

  

  

  

}

  

  

]

  

}

}

POST

https://core.shopimind.com/v1/custom-stats/kpis

Playground

Headers

spm-api-key*

Body

Samples

Create a custom KPI Creates a custom KPI: measures aggregated hour by hour from a source (system schema or custom data definition) into a dedicated aggregate table, kept up to date by a scheduled event. Field paths must come from listCustomKpiFields. The KPI is returned with status: backfilling while its history (lookback_max_months, 12 by default) is computed asynchronously. Use previewCustomKpi to check a configuration before creating it. POST /v1/custom-stats/kpis createCustomKpi Custom KPIs spm-api-key [Authentication] Required API key, in the form {prefix}.{secret}. Custom KPI created successfully. Client error - Invalid request or authentication issues Server error - Internal processing failure