Run a reporting query

Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

const result = await client.reporting.query({
  metrics: ['total_sales', 'orders'],
  dimensions: [{ name: 'completed_at', grain: 'day' }],
  time_range: { preset: 'last_7_days' },
  compare: 'previous_period',
})

{
  "meta": {
    "currency": "USD",
    "time_range": {
      "since": "2026-01-08T00:00:00Z",
      "until": "2026-01-15T23:59:59Z"
    },
    "previous_time_range": {
      "since": "2025-12-31T00:00:00Z",
      "until": "2026-01-07T23:59:59Z"
    },
    "metrics": [
      "total_sales",
      "orders"
    ],
    "dimensions": [
      {
        "name": "completed_at",
        "grain": "day"
      }
    ]
  },
  "totals": {
    "total_sales": {
      "value": "110.00",
      "previous": "0.00",
      "growth": null,
      "display": "$110.00"
    },
    "orders": {
      "value": 1,
      "previous": 0,
      "growth": null
    }
  },
  "rows": [
    {
      "dimensions": {
        "completed_at": "2026-01-08"
      },
      "metrics": {
        "total_sales": {
          "value": "0.00",
          "previous": "0.00",
          "growth": "0",
          "display": "$0.00"
        },
        "orders": {
          "value": 0,
          "previous": 0,
          "growth": "0"
        }
      }
    },
    {
      "dimensions": {
        "completed_at": "2026-01-09"
      },
      "metrics": {
        "total_sales": {
          "value": "0.00",
          "previous": "0.00",
          "growth": "0",
          "display": "$0.00"
        },
        "orders": {
          "value": 0,
          "previous": 0,
          "growth": "0"
        }
      }
    },
    {
      "dimensions": {
        "completed_at": "2026-01-10"
      },
      "metrics": {
        "total_sales": {
          "value": "0.00",
          "previous": "0.00",
          "growth": "0",
          "display": "$0.00"
        },
        "orders": {
          "value": 0,
          "previous": 0,
          "growth": "0"
        }
      }
    },
    {
      "dimensions": {
        "completed_at": "2026-01-11"
      },
      "metrics": {
        "total_sales": {
          "value": "0.00",
          "previous": "0.00",
          "growth": "0",
          "display": "$0.00"
        },
        "orders": {
          "value": 0,
          "previous": 0,
          "growth": "0"
        }
      }
    },
    {
      "dimensions": {
        "completed_at": "2026-01-12"
      },
      "metrics": {
        "total_sales": {
          "value": "0.00",
          "previous": "0.00",
          "growth": "0",
          "display": "$0.00"
        },
        "orders": {
          "value": 0,
          "previous": 0,
          "growth": "0"
        }
      }
    },
    {
      "dimensions": {
        "completed_at": "2026-01-13"
      },
      "metrics": {
        "total_sales": {
          "value": "110.00",
          "previous": "0.00",
          "growth": null,
          "display": "$110.00"
        },
        "orders": {
          "value": 1,
          "previous": 0,
          "growth": null
        }
      }
    },
    {
      "dimensions": {
        "completed_at": "2026-01-14"
      },
      "metrics": {
        "total_sales": {
          "value": "0.00",
          "previous": "0.00",
          "growth": "0",
          "display": "$0.00"
        },
        "orders": {
          "value": 0,
          "previous": 0,
          "growth": "0"
        }
      }
    },
    {
      "dimensions": {
        "completed_at": "2026-01-15"
      },
      "metrics": {
        "total_sales": {
          "value": "0.00",
          "previous": "0.00",
          "growth": "0",
          "display": "$0.00"
        },
        "orders": {
          "value": 0,
          "previous": 0,
          "growth": "0"
        }
      }
    }
  ]
}

POST

api

admin

reporting

query

Spree Admin SDK

import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://your-store.com',
  secretKey: 'sk_xxx',
})

const result = await client.reporting.query({
  metrics: ['total_sales', 'orders'],
  dimensions: [{ name: 'completed_at', grain: 'day' }],
  time_range: { preset: 'last_7_days' },
  compare: 'previous_period',
})

{
  "meta": {
    "currency": "USD",
    "time_range": {
      "since": "2026-01-08T00:00:00Z",
      "until": "2026-01-15T23:59:59Z"
    },
    "previous_time_range": {
      "since": "2025-12-31T00:00:00Z",
      "until": "2026-01-07T23:59:59Z"
    },
    "metrics": [
      "total_sales",
      "orders"
    ],
    "dimensions": [
      {
        "name": "completed_at",
        "grain": "day"
      }
    ]
  },
  "totals": {
    "total_sales": {
      "value": "110.00",
      "previous": "0.00",
      "growth": null,
      "display": "$110.00"
    },
    "orders": {
      "value": 1,
      "previous": 0,
      "growth": null
    }
  },
  "rows": [
    {
      "dimensions": {
        "completed_at": "2026-01-08"
      },
      "metrics": {
        "total_sales": {
          "value": "0.00",
          "previous": "0.00",
          "growth": "0",
          "display": "$0.00"
        },
        "orders": {
          "value": 0,
          "previous": 0,
          "growth": "0"
        }
      }
    },
    {
      "dimensions": {
        "completed_at": "2026-01-09"
      },
      "metrics": {
        "total_sales": {
          "value": "0.00",
          "previous": "0.00",
          "growth": "0",
          "display": "$0.00"
        },
        "orders": {
          "value": 0,
          "previous": 0,
          "growth": "0"
        }
      }
    },
    {
      "dimensions": {
        "completed_at": "2026-01-10"
      },
      "metrics": {
        "total_sales": {
          "value": "0.00",
          "previous": "0.00",
          "growth": "0",
          "display": "$0.00"
        },
        "orders": {
          "value": 0,
          "previous": 0,
          "growth": "0"
        }
      }
    },
    {
      "dimensions": {
        "completed_at": "2026-01-11"
      },
      "metrics": {
        "total_sales": {
          "value": "0.00",
          "previous": "0.00",
          "growth": "0",
          "display": "$0.00"
        },
        "orders": {
          "value": 0,
          "previous": 0,
          "growth": "0"
        }
      }
    },
    {
      "dimensions": {
        "completed_at": "2026-01-12"
      },
      "metrics": {
        "total_sales": {
          "value": "0.00",
          "previous": "0.00",
          "growth": "0",
          "display": "$0.00"
        },
        "orders": {
          "value": 0,
          "previous": 0,
          "growth": "0"
        }
      }
    },
    {
      "dimensions": {
        "completed_at": "2026-01-13"
      },
      "metrics": {
        "total_sales": {
          "value": "110.00",
          "previous": "0.00",
          "growth": null,
          "display": "$110.00"
        },
        "orders": {
          "value": 1,
          "previous": 0,
          "growth": null
        }
      }
    },
    {
      "dimensions": {
        "completed_at": "2026-01-14"
      },
      "metrics": {
        "total_sales": {
          "value": "0.00",
          "previous": "0.00",
          "growth": "0",
          "display": "$0.00"
        },
        "orders": {
          "value": 0,
          "previous": 0,
          "growth": "0"
        }
      }
    },
    {
      "dimensions": {
        "completed_at": "2026-01-15"
      },
      "metrics": {
        "total_sales": {
          "value": "0.00",
          "previous": "0.00",
          "growth": "0",
          "display": "$0.00"
        },
        "orders": {
          "value": 0,
          "previous": 0,
          "growth": "0"
        }
      }
    }
  ]
}

Authorizations

x-spree-api-key

string

header

required

Secret API key for admin access

Authorization

string

header

required

JWT token for admin user authentication

Headers

x-spree-api-key

string

required

Authorization

string

required

Body

application/json

metrics

string[]

required

Registered metric names, from the reporting schema endpoint.

dimensions

any[]

Up to 2 dimensions to break the metrics down by. Each is a dimension name, or { name, grain, include_empty }: grain (hour, day, week, month) buckets a time dimension, and include_empty lists members with no matching rows where the schema entry supports it.

filters

object[]

Narrows the rows by dimension value.

Show child attributes

metric_filters

object[]

Filters on an aggregate, such as units_sold = 0. Narrows the rows only; the totals stay the period's real figure. The metric must also appear in metrics, and cannot be a derived one.

Show child attributes

time_range

object

A named preset (last_month, week_to_date, any last_<n>_<days|weeks|months>), or ISO 8601 dates or times in since and until (a bare date covers the store's whole day). Defaults to the last 30 days, in the store's time zone.

Show child attributes

compare

enum<string>

Available options:

previous_period,

previous_year

sort

string

A metric name; prefix it with - to sort descending.

limit

integer

At most 1000.

currency

enum<string>

Available options:

AED,

AFN,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BTN,

BWP,

BYN,

BYR,

BZD,

CAD,

CDF,

CHF,

CLF,

CLP,

CNY,

COP,

CRC,

CUC,

CUP,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EEK,

EGP,

ERN,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

INR,

IQD,

IRR,

ISK,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KPW,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LTL,

LVL,

LYD,

MAD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRO,

MRU,

MTL,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SDG,

SEK,

SGD,

SHP,

SKK,

SLE,

SLL,

SOS,

SRD,

SSP,

STD,

STN,

SVC,

SYP,

SZL,

THB,

TJS,

TMM,

TMT,

TND,

TOP,

TRY,

TTD,

TWD,

TZS,

UAH,

UGX,

USD,

UYI,

UYU,

UYW,

UZS,

VED,

VEF,

VES,

VND,

VUV,

WST,

XAF,

XCD,

XCG,

XOF,

XPF,

YER,

ZAR,

ZMK,

ZMW,

ZWD,

ZWG,

ZWL,

ZWN,

ZWR

Response

200 - application/json

query results

⌘I

API basics

Endpoints

Authorizations

Headers

Body

Response