Skip to content

Update a saved report

PATCH
/stores/{storeRef}/reports/{id}
curl --request PATCH \
--url https://apibase.ecomweb.app/api/v1/stores/example/reports/example \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "definition": { "dimensions": [ { "grain": "day", "field": "example" } ], "filters": [ { "operator": "is", "values": [ "example" ], "field": "example" } ], "date_range": { "start": "example", "end": "example" }, "sort": [ { "order": "asc", "key": "example" } ], "visualization": "table", "v": 1, "dataset": "example", "measures": [ "example" ], "limit": 1 }, "name": "example" }'

Renames a saved report, replaces its definition, or both, and returns it. Fields you leave out are unchanged. Renaming to a name another report uses answers 409 with the code report_name_taken.

Required scopes: write:analytics

id
required
string

The saved report ID, a decimal string.

storeRef
required
string

The store’s ref, as returned by GET /stores.

Media typeapplication/json
object
definition

The definition that replaces the saved one.

object
dimensions

Dimensions to group by, at most 4, without duplicates.

Array<object>
object
grain

Time grain for a date dimension: day, week, month, quarter or year.

string
Allowed values: day week month quarter year
field
required

Key of a dimension of the dataset.

string
<= 100 characters
filters

Conditions that narrow the rows.

Array<object>
object
operator
required

How to compare: is, is_not, gte or lte. Which of them a filter accepts is listed in the report schema.

string
<= 100 characters
Allowed values: is is_not gte lte
values
required

The values to compare with, up to the limit the filter allows. Numbers and booleans are read as text.

Array
field
required

Key of a filter of the dataset.

string
<= 100 characters
date_range
required

The days the report covers.

object
start
required

First day, inclusive, as YYYY-MM-DD in the store’s time zone.

string
end
required

Last day, inclusive, as YYYY-MM-DD in the store’s time zone. At most 5 years after start.

string
sort

How to sort the rows.

Array<object>
object
order
required

Sort direction.

string
Allowed values: asc desc
key
required

Key of a selected measure or dimension to sort by.

string
<= 100 characters
visualization

How the dashboard draws the report: table, line or bar. It does not change the rows.

string
Allowed values: table line bar
v

Version of the definition format. The API always reads it as the current version.

number
dataset
required

Key of the dataset to read, such as orders. Dataset keys are listed in the report schema.

string
<= 100 characters
measures
required

Keys of the measures to calculate, from 1 to 8, without duplicates.

Array<string>
limit

Maximum number of rows, from 1 to 1000. Defaults to 100.

number
>= 1 <= 1000
name

New report name, 1 to 100 characters.

string
>= 1 characters <= 100 characters
Media typeapplication/json
object
definition
required

The saved definition.

object
dimensions
required

Dimensions to group by.

Array<object>
object
grain

Time grain for a date dimension: day, week, month, quarter or year.

string
Allowed values: day week month quarter year
field
required

Key of a dimension of the report’s dataset.

string
filters
required

Conditions that narrow the rows.

Array<object>
object
operator
required

How the values are compared.

string
Allowed values: is is_not gte lte
field
required

Key of a filter of the report’s dataset.

string
values
required

The values to compare with. is and is_not match any of the values.

Array<string>
date_range
required

The days the report covers.

object
start
required

First day, inclusive, as YYYY-MM-DD in the store’s time zone.

string
end
required

Last day, inclusive, as YYYY-MM-DD in the store’s time zone.

string
sort
required

How the rows are sorted.

Array<object>
object
order
required

Sort direction.

string
Allowed values: asc desc
key
required

Key of a selected measure or dimension.

string
visualization

How the dashboard draws the report. It does not change the rows.

string
Allowed values: table line bar
v
required

Version of the definition format.

number
dataset
required

Key of the dataset the report reads, such as orders.

string
measures
required

Keys of the measures to calculate.

Array<string>
limit
required

Maximum number of rows.

number
id
required

Saved report ID, as a decimal string.

string
created_by_user_id
required

ID of the user who saved the report, or whose API key saved it.

string
name
required

Report name.

string
created_at
required

When the report was saved, as an ISO 8601 timestamp.

string
updated_at
required

When the report was last changed, as an ISO 8601 timestamp.

string

Example

{
"definition": {
"dimensions": [
{
"grain": "day"
}
],
"filters": [
{
"operator": "is"
}
],
"sort": [
{
"order": "asc"
}
],
"visualization": "table"
}
}

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The resource does not exist in this store.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The request conflicts with the resource’s current state.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}