Developer REST API

Overview

Dashboardly Developer REST API lets an eligible account connect a custom client dashboard, data warehouse, ERP, or other backend directly to Dashboardly using standard HTTPS and JSON.

This is separate from the Model Context Protocol (MCP):

use MCP when an AI assistant such as Claude, ChatGPT, or Cursor should ask questions about Dashboardly data;
use the Developer REST API when your own backend code should request data from fixed URLs and process JSON responses.

Developer REST is normally available when Dashboardly has enabled it for an account on a current Agency plan. Dashboardly can also approve an account-specific exception for a Brand account without changing its plan. An approved exception works only while that Brand subscription is active or in trial. If the qualifying subscription is cancelled, paused, or falls behind on payment, existing Developer keys stop working until the plan is current again — the keys themselves are not deleted, and access returns as soon as the subscription is active. Most routes are read-only. Dated COGS and manual adjustments have separate permissions that an account owner/admin must explicitly enable.

Open the API documentation

Interactive Swagger: https://api.dashboardly.io/api/developer/docs
OpenAPI JSON: https://api.dashboardly.io/api/developer/openapi.json
API base URL: https://api.dashboardly.io/api/developer/v1

Swagger lists every current route, query field, body, permission, response envelope, and error contract. The OpenAPI JSON can generate a typed client for your preferred language.

Create a Developer API key

Sign in as the account owner/admin.
Open Settings > API Keys.
Select New API key and give it a descriptive name.
Select one shop or all shops.
Turn on Allow private Developer REST API.
For a trusted accounting or warehouse backend only, optionally enable Allow Manual Adjustments changes or Allow dated COGS uploads. Either write option requires one selected shop.
Create and immediately store the one-time secret in your server's secret manager.

Never expose the key in browser JavaScript, a mobile application, a public repository, analytics, or logs. Your own backend should call Dashboardly and return only the data your client-facing page needs.

Authenticate a request

Send the key as a Bearer token:

curl https://api.dashboardly.io/api/developer/v1/account \
  -H "Authorization: Bearer $DASHBOARDLY_API_KEY"

Start with GET /account, then GET /shops. When a key can access more than one connected shop, send the selected Dashboardly shop UUID as shopId on module requests. This includes reading one manual adjustment by ID.

Available data

The API covers Dashboardly's customer-facing analytics modules:

Dashboard overview and top products;
Profit & Loss, published Custom P&L, and Sales & Profit;
Cashflow and payout ledger;
orders, status statistics, hourly/geographic aggregates, and refunds;
inventory, dated COGS coverage, and warehouse fees;
customer summary, pseudonymized customer LTV, cohorts, and journeys;
marketing overview, ad campaigns, LIVE, promotions, and affiliate performance;
manual-adjustment ledger.

Cashflow, Marketing, LIVE, and Affiliate endpoints are also controlled by the feature availability of the selected shop.

Billing, subscriptions, collaborators, API-key administration, imports, and Dashboardly settings are not exposed through this analytics API.

Privacy

Order responses exclude buyer names, email addresses, phone numbers, recipient addresses, and tracking identifiers. Customer endpoints return aggregate data or a stable account-local pseudonym rather than the original buyer identifier. Customer rows do not expose concrete first/last order IDs. Small geographic groups are combined into Other.

Optional writes

Dated COGS

POST /costs writes Dashboardly's effective-dated product/SKU Unit COG timeline. It never changes TikTok Shop. The key must have write:costs, be limited to one shop, and reference products/SKUs from that shop.

Manual adjustments

Manual-adjustment writes require write:manual-adjustments and a key limited to one shop. Creating an adjustment and importing COGS both require an Idempotency-Key header so retrying a timed-out request cannot duplicate an accounting entry. An API key can update, suspend, resume, or delete only adjustments that it created in its selected shop. Dates are calendar YYYY-MM-DD values, end dates cannot precede start dates, timezones must be valid IANA names, and custom per-SKU amounts must reference IDs listed in skuIds.

Errors and rate limits

Successful responses contain data and meta. Errors contain error.code, error.message, and meta.requestId. Keep the request ID when contacting support.

The default limit is 120 requests per minute per key, with an additional IP backstop. If the API returns 429, wait for the reported retryAfter interval and retry with exponential backoff.

Get help

Dashboardly can help you select scopes, connect your account, and test the integration. Book an onboarding call at https://cal.com/dashboardly/onboarding.