Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sellfern.com/llms.txt

Use this file to discover all available pages before exploring further.

The Analytics API provides programmatic access to the same financial metrics shown in the Sellfern Analytics dashboard, including revenue, COGS, margins, and order counts. Use it to build reporting automation, feed data into external BI tools, or power agent-driven summaries. All analytics endpoints require the analytics:read scope when called with an API token.

​
GET /api/v2/analytics/summary

Get an aggregated revenue and profit summary for a time period. This endpoint returns a fixed-shape response that is easy for scripts and agents to parse reliably. Required scope: analytics:read

​
Query parameters

​
period
string
default:"last_30_days"
A preset time period. Accepted values: last_7_days, last_30_days, mtd (month-to-date), ytd (year-to-date).
​
start_date
string
Start of a custom date range (ISO 8601, e.g. 2026-01-01). Use start_date and end_date together as an alternative to period.
​
end_date
string
End of a custom date range (ISO 8601, e.g. 2026-01-31).
​
store_id
integer
Filter results to a specific store by its numeric ID.
​
timezone
string
default:"UTC"
IANA timezone string used to interpret date boundaries (e.g. America/New_York).

​
Example

curl -X GET "https://api.sellfern.com/api/v2/analytics/summary?period=last_7_days" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE"

{
  "success": true,
  "data": {
    "period": "last_7_days",
    "start_date": "2026-04-19",
    "end_date": "2026-04-26",
    "revenue": 12450.00,
    "order_count": 87,
    "cogs": 6225.00,
    "gross_profit": 6225.00,
    "margin_pct": 50.0
  },
  "meta": { "request_id": "req_abc123" }
}

​
Response fields

​
period
string
The period label returned (matches the period parameter, or custom for date-range requests).
​
start_date
string
The start date of the reporting window (ISO 8601).
​
end_date
string
The end date of the reporting window (ISO 8601).
​
revenue
number
Total gross revenue for the period.
​
order_count
integer
Number of orders included in the period.
​
cogs
number
Total cost of goods sold for the period.
​
gross_profit
number
Gross profit (revenue minus COGS).
​
margin_pct
number
Gross margin as a percentage (gross_profit / revenue × 100).
The summary endpoint reflects product COGS only. Operating expenses such as Etsy fees, advertising spend, and other overhead tracked separately in the Sellfern UI are not included in cogs or gross_profit unless they have been assigned as order-level costs.

​
GET /api/v2/analytics/by-store

Get analytics broken down by individual store. Returns a flat array where each entry represents one store’s metrics for the requested period. Required scope: analytics:read

​
Query parameters

​
period
string
default:"last_30_days"
A preset time period. Accepted values: last_7_days, last_30_days, mtd, ytd.
​
timezone
string
default:"UTC"
IANA timezone string used to interpret date boundaries (e.g. America/Chicago).

​
Example

curl -X GET "https://api.sellfern.com/api/v2/analytics/by-store?period=last_30_days" \
  -H "Authorization: Bearer sk_live_YOUR_TOKEN_HERE"

{
  "success": true,
  "data": [
    {
      "storeName": "Sunrise Prints",
      "revenue": 8200.00,
      "orders": 54,
      "profit": 3100.00
    },
    {
      "storeName": "Pine & Oak Goods",
      "revenue": 4250.00,
      "orders": 33,
      "profit": 1540.00
    }
  ],
  "meta": { "request_id": "req_abc456" }
}