Introduction
Guides
API Reference
SPI CRM v2
SPI CRM v1
SPI Events
SPI Gift Card
SPI Insurance
SPI Payment
SPI Product Recommendations
SPI Product Search
SPI RFID
SPI Tax Free
Journals v3
Purchase Prices v3
Shipments v3

Custom Metrics API

Add Custom Metric

post /custom_metrics

Adds a new metric which will be immutable and can only be deleted.

REQUEST BODY
object
REQUIRED

Custom Metric Object

CustomMetric
Returns

Returns the added Custom Metric object.

CustomMetric
posthttps://api.mysitoo.com/v2/accounts/1500/custom_metrics.json
RESPONSE JSON
{
  "key": "cm_revenue_total_budget",
  "grouping": "date_store",
  "type": "scalar",
  "format": "money"
}
HTTP Status Code Summary
201Returns the added Custom Metric object.
400Invalid request
401Unauthorized
429Too many requests
500Internal Server Error

Get Custom Metrics

get /custom_metrics

Get list of Custom Metrics. Use filter keys to filter out specific Custom Metrics.

PARAMETERS
keys
string
query

An optional comma separated list of Custom Metric keys to retrieve.

Returns

Arra of Custom Metrics

CustomMetric
array
gethttps://api.mysitoo.com/v2/accounts/1500/custom_metrics.json?keys=cm_revenue_total_budget
RESPONSE JSON
[
  {
    "key": "cm_revenue_total_budget",
    "grouping": "date_store",
    "type": "scalar",
    "format": "money"
  }
]
HTTP Status Code Summary
200Arra of Custom Metrics
401Unauthorized
429Too many requests

Delete Custom Metric

delete /custom_metrics/{key}

Delete a Custom Metric and all data associated with it.

PARAMETERS
key
string
path
REQUIRED

Key of the metric

delete/custom_metrics/{key}
HTTP Status Code Summary
200Custom Metric deleted OK
401Unauthorized
404Custom Metric key does not exist
429Too many requests
500An error occurred deleting Custom Metric or its values

Get Custom Metric Values

get /custom_metric_values

Get list of Custom Metric Values. All metrics that match the filter will be returned. Note that query parameters for date and store only filter values that are grouped on them. E.g. a metric grouped on store_id will be returned if the query param for store_id matches (regardless if query parameter for date is passed or not)

PARAMETERS
keys
string
query

Comma separated list of keys for metrics to retreive.

date
string
query

The first date to retrieve values for in valid ISO format (YYYY-MM-DD).

num_days
integer
query

Number of days to retrieve values for. Default is 1. Min is 1 and max is 100

Default: 1
store_id
string
query

The ID for the store that the Custom Metric data belongs to.

Returns

CustomMetricValue
array
gethttps://api.mysitoo.com/v2/accounts/1500/custom_metric_values.json?keys=cm_revenue_total_budget&store_id=12345&date=2020-12-11&num_days=5
RESPONSE JSON
[
  {
    "key": "cm_revenue_total_budget",
    "date": "2020-12-11",
    "store_id": "12345",
    "value_scalar": 10000
  },
  {
    "key": "cm_revenue_total_budget",
    "date": "2020-12-12",
    "store_id": "12345",
    "value_scalar": 15000
  },
  {
    "key": "cm_revenue_total_budget",
    "date": "2020-12-13",
    "store_id": "12345",
    "value_scalar": 11000
  },
  {
    "key": "cm_revenue_total_budget",
    "date": "2020-12-14",
    "store_id": "12345",
    "value_scalar": 7000
  },
  {
    "key": "cm_revenue_total_budget",
    "date": "2020-12-15",
    "store_id": "12345",
    "value_scalar": 10000
  }
]
HTTP Status Code Summary
200
400Invalid request
401Unauthorized
429Too many requests

Update Custom Metric Values

put /custom_metric_values

Set values for Custom Metrics

REQUEST BODY
array
REQUIRED

Array of Custom Metric Value objects

CustomMetricValue
Returns

CustomMetricValue
array
puthttps://api.mysitoo.com/v2/accounts/1500/custom_metric_values.json
[
  {
    "key": "cm_revenue_total_budget",
    "date": "2020-12-11",
    "store_id": "12345",
    "value_scalar": 10000
  },
  {
    "key": "cm_revenue_total_budget",
    "date": "2020-12-12",
    "store_id": "12345",
    "value_scalar": 15000
  },
  {
    "key": "cm_revenue_total_budget",
    "date": "2020-12-13",
    "store_id": "12345",
    "value_scalar": 11000
  },
  {
    "key": "cm_revenue_total_budget",
    "date": "2020-12-14",
    "store_id": "12345",
    "value_scalar": 7000
  },
  {
    "key": "cm_revenue_total_budget",
    "date": "2020-12-15",
    "store_id": "12345",
    "value_scalar": 10000
  }
]
RESPONSE JSON
[
  {
    "key": "cm_revenue_total_budget",
    "date": "2020-12-11",
    "store_id": "12345",
    "value_scalar": 10000
  },
  {
    "key": "cm_revenue_total_budget",
    "date": "2020-12-12",
    "store_id": "12345",
    "value_scalar": 15000
  },
  {
    "key": "cm_revenue_total_budget",
    "date": "2020-12-13",
    "store_id": "12345",
    "value_scalar": 11000
  },
  {
    "key": "cm_revenue_total_budget",
    "date": "2020-12-14",
    "store_id": "12345",
    "value_scalar": 7000
  },
  {
    "key": "cm_revenue_total_budget",
    "date": "2020-12-15",
    "store_id": "12345",
    "value_scalar": 10000
  }
]
HTTP Status Code Summary
200
400Invalid request
401Unauthorized
429Too many requests
500One or more of the requested items could not be inserted

Delete Custom Metric Values

delete /custom_metric_values/{key}

All values for Custom Metrics that match the filter will be deleted. Note that query parameters for date and store only filter values that are grouped on them. E.g. a metric grouped on store_id will be matched if the query param for store_id matches (regardless if query parameter for date is passed or not)

PARAMETERS
key
string
path
REQUIRED

Key of the metric to delete data for.

date
string
query

Date of the metric values to delete in ISO format (YYYY-MM-DD).

num_days
string
query

Number of days starting from date to delete values from. Default is 1. Min is 1 and max is 100.

Default: 1
store_id
string
query

Deletes data only for this Store

deletehttps://api.mysitoo.com/v2/accounts/1500/custom_metric_values/cm_revenue_total_budget.json
HTTP Status Code Summary
200Custom Metric Values deleted OK
400Invalid input
401Unauthorized
404Custom Metric key does not exist
429Too many requests
500One or more of the requested items could not be deleted.

Objects

CustomMetric
object

PROPERTIES
key
string
REQUIRED

The name of the Custom Metric. Must start with "cm_"

Pattern: ^cm_[a-z0-9_]+$
grouping
string
REQUIRED
  • none No grouping. Only one value can exist.
  • date Group by date. One value per date is possible.
  • store Group by store. One value per store is possible.
  • date_store Group by store and date. One value per store and date is possible.
VALUES
none
date
store
date_store
type
string
REQUIRED
  • scalar Scalar Metric
  • series Series Metric
VALUES
scalar
series
format
string
  • number Numeric value
  • integer Integer value
  • money Money value (^[-+]?[0-9]+.[0-9]{2}$)
  • percent Percentage value
Default: "number"
VALUES
number
integer
money
percent

CustomMetricValue
object

PROPERTIES
key
string
REQUIRED

The name of the Custom Metric

Pattern: ^cm_[a-z0-9_]+$
date
string

Required if metric grouping is date or date_store

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

Required if metric grouping is store or date_store (Dashboard engine will map this value to the External ID of store)

value_scalar
number

Value. Set if metric type is scalar

value_series
object

Series. Set if metric type is series

total_count
integer
(int64)
REQUIRED

The total number of items for the series (The returned series may not include all items)

total_value
number
REQUIRED

The total value for the series (The actual series may not include all values)

series
array
(object)
REQUIRED
PROPERTIES
label
string
value
number

Error
object

PROPERTIES
statuscode
integer
REQUIRED

An http status code

errortext
string
REQUIRED

Text describing the error

Copyright © 2025 Sitoo AB. All rights reserved.