Connecting AI Assistants to Dashboardly

Overview

Dashboardly lets you connect an AI assistant such as ChatGPT, Claude, or Cursor so it can answer questions about your TikTok Shop data in plain English. You ask "What was my net profit last week?" or "Which SKU sold most yesterday in my UK shop?" and the assistant pulls the answer directly from your live Dashboardly data.

The connection uses an open standard called the Model Context Protocol (MCP). ChatGPT and Claude Desktop can use Dashboardly account sign-in (OAuth), while developer tools can use an API key. With OAuth, one connector can cover all shops you can access, only shops you select, or only the shop that was active when you signed in.

API Keys are read-only by default. An AI assistant can read the analytics areas listed below, but it cannot create orders, edit settings, send refunds, or modify anything in TikTok Shop. A shop owner or admin can separately create a one-shop key with dated COGS upload permission for a trusted warehouse or ERP integration; that permission is disabled by default and is not exposed as an AI/MCP action. Some specialized Dashboardly pages do not yet have a dedicated MCP tool; the current coverage is stated explicitly below.

You manage all keys on the Settings > API Keys page.

Plan Requirements

API Keys are part of Dashboardly's AI Integrations feature, available on the following plans:

If you are on Brand Starter, the API Keys tab in Settings shows an upgrade prompt. Upgrade your subscription on the Settings > Subscriptions page to enable the feature.

There is no per-key fee. An eligible account can keep up to five API keys active at a time, with no extra charge for the queries an AI assistant makes. Revoke a key you no longer use before creating another one when all five slots are occupied.

How It Works

With Dashboardly account sign-in, the consent screen asks which shops the connector may use:

• All shops I can access (recommended) follows your current Dashboardly access. Newly assigned shops become available, while disconnected shops or removed collaborator assignments stop being available automatically.
• Selected shops only limits the connector to the shops you check and still respects later access removals.
• Current shop only keeps the connection limited to the shop that was active when you signed in.

Existing OAuth connections created before multi-shop selection remain limited to their original shop. Revoke and reconnect the app to choose a different scope.

When you create an API key in Dashboardly, two things happen:

1. The key is generated. It looks like dk_live_... followed by a long random string. You see the full key exactly once, at the moment of creation. After that, Dashboardly stores only a fingerprint of it, so even our support team cannot retrieve the full key later.
2. The key is bound to your account. Each key is tied to your Dashboardly login and, optionally, to a single TikTok Shop. When an AI assistant uses the key to ask for data, it gets back exactly what you would see if you opened that shop in your browser.

Your AI assistant connects to a Dashboardly endpoint (the MCP server) and presents the key. The endpoint verifies the key, looks up which shop the key is allowed to read, and returns the requested data. Dashboardly records request metadata on a best-effort basis — which key and shop were used, which data area was queried, when, and whether it succeeded — so you can see how often your assistant is using the key. It does not record the questions you ask or the data that was returned. See Security & Privacy below for exactly what is and is not recorded.

MCP report tools remain read-only. Optional dated COGS and manual-adjustment write permissions belong to the separate Agency Developer REST API and are not available as AI/MCP actions. Developer REST has its own interactive reference at https://api.dashboardly.io/api/developer/docs.

For shops with Custom P&L enabled, the get_custom_pnl tool can list published saved reports, discover their immutable prepared evaluations, and page through the same SKU/day values used by the Dashboardly report and Excel export. It cannot edit report rows, formulas, mappings, allocations, or source data, and it never starts a new calculation.

Daily Financial Export for Automations

The read-only get_daily_financials MCP tool gives a server-side automation a complete daily financial series in one request. Choose JSON when your program will process the result, or CSV when it should save or forward a spreadsheet- ready file. The export includes every calendar day in the requested shop-local date range, including explicit zero-value days, and returns Gross Sales, Net Sales, buyer-paid checkout total, platform subsidy, platform commission, co-funded promotion fee, Net Ad Spend, Net Profit, active paid order count, and the count of orders that do not yet have a payment row.

buyerPaid uses TikTok's order payment total and excludes sample, cancelled, and unpaid orders. Separate including-cancelled and cancelled-only values make reconciliation explicit. Platform commission and co-funded promotion fee keep Dashboardly's signed expense convention (normally negative), while Net Ad Spend is returned as a positive cost. Dashboardly calculates the financial columns through the same canonical Profit & Loss services used by the app; the automation should not rebuild Net Profit from raw order fields.

Dashboardly provides the read-only data call, but it does not run a customer's private Node.js process or email files on the customer's behalf. Run the MCP call from a trusted server-side cron job, n8n workflow, or cloud scheduler and store the key as a secret. Dates are interpreted in the shop timezone supplied by list_shops; do not send the API key by email or embed it in source code.

Exporting Profitability at Shop, Product, SKU, and Order Level

Your read-only key can retrieve profitability at the level that matches your workflow. Shop totals are available through Dashboard and Profit & Loss data; product and SKU rows are available through Sales & Profit; individual orders can include their complete financial reconciliation. These results use Dashboardly's canonical metric services, including dated COGS, shipping, TikTok fees, manual expenses, ad spend, and preliminary-data indicators.

For an AI assistant, ask for Sales & Profit and specify whether you want one row per product or one row per SKU. Results are paginated, so the assistant can request additional pages until every row has been read. For a server-to-server integration, request GET /api/developer/v1/sales-profit with grain=product or grain=sku. Use the returned pagination details to continue until hasMore is false. The response preserves every profitability field rather than returning only a small fixed set of metrics.

For order-level exports, request orders with financials included. Buyer name, email, phone, address, and tracking details are always excluded, while TikTok Order IDs, Product/SKU IDs, quantities, settlement status, revenue, COGS, shipping, fees, and order profit remain available. This gives warehouse, finance, and reporting systems useful financial data without exposing buyer personal information.

Product Profitability Responses and Filters

The Sales & Profit MCP tool returns the requested product or SKU rows before optional explanatory details, so a large catalog or a detailed data-quality report does not crowd the profitability rows out of the response. Product rows include the complete Dashboardly profitability result, including Ad Spend, Referral Fee, Customer-paid Shipping, Shipping Cost, COGS, Operating Profit, and Net Profit. Ask for one row per SKU when you need variant-level costs and profitability.

By default, the summary and product rows use the same search, Product ID, and SKU filters. The response labels this as summaryScope: "filtered". This means that if you search for one product, the summary describes that product instead of silently showing the whole shop. An integration that intentionally needs shop totals beside filtered product rows can request summaryScope: "whole_shop"; the response labels the different scope explicitly. Filtered summaries use the product-attributed Ad Spend rows, and allocated overhead/manual expenses are applied before Operating Profit and Net Profit are returned, so the visible deductions are not omitted from the profit totals. When TikTok publishes product-level ad revenue without product-level cost, Dashboardly uses the same product-sales allocation as the Sales & Profit cards instead of treating that product's Ad Spend as zero.

Detailed finality notes and the full SKU catalog are optional because they can be much larger than the requested profitability data:

• includeDataQuality: false is the default and returns a compact preliminary versus final summary. Set it to true only when you need the per-metric finality detail.
• includeSkuCatalog: false is the default. Use the SKU breakdown when you need SKU profitability; set this option to true only when you also need every catalog SKU attached to each product.

Ad campaign results come from Dashboardly's imported, shop-specific TikTok Ads data. A response distinguishes between available data, a sync in progress, stale recent data being refreshed, and a date range with no campaign-level attribution. An empty campaign list therefore does not automatically mean your whole-shop Ad Spend is zero; ask for the Marketing Overview total when TikTok does not provide campaign-level rows for the period.

Developer REST API for Custom Integrations

Agency customers on a current Agency plan can use the separate Developer REST API from their own server-side code, once Dashboardly enables it for the account. It is standard HTTPS/JSON rather than MCP and covers the Dashboardly analytics modules, including Dashboard, Profit & Loss, Sales & Profit, Cashflow, Orders, Inventory, Warehouse, Customers, Marketing, refunds, and manual adjustments.

Reading is the default. Two write capabilities exist and each needs its own permission on a key scoped to exactly one shop: dated COGS uploads (write:costs) and manual-adjustment management — create, update, delete, suspend, resume (write:manual-adjustments). A key can only change the adjustments it created itself.

Open the full Swagger reference at https://api.dashboardly.io/api/developer/docs or use the machine-readable OpenAPI document at https://api.dashboardly.io/api/developer/openapi.json. See Connect Your Backend with the Developer REST API for the setup, privacy, and permission model.

What “Allow dated COGS uploads” Does

The checkbox does not connect Claude, ChatGPT, or another cloud service by itself. It adds a narrowly scoped write:costs permission to the API key you are creating.

When enabled, your own trusted warehouse or ERP backend can send up to 1,000 dated product/SKU costs per request to:

POST https://api.dashboardly.io/api/developer/v1/costs

Each row contains a Dashboardly/TikTok Product ID, an optional SKU ID, a Unit COG, and an inclusive YYYY-MM-DD Effective Date. A product row becomes the product-level default; a SKU row overrides that default for the selected SKU from its Effective Date onward.

The permission is available only when all of these are true:

• the person creating the key is an owner or admin;
• exactly one shop is selected;
• Allow dated COGS uploads is checked.

Existing keys, merchant-wide keys, and default read-only keys cannot write costs. The endpoint updates Dashboardly's dated cost history only; it never writes to TikTok Shop. Keep this dedicated key on your server, not in browser or mobile code.

Step-by-Step: Create Your First API Key

Step 1: Open the API Keys page

Navigate to Settings > API Keys in the left sidebar. If you don't see the tab, check that your subscription is on Brand Growing or higher.

Step 2: Click "New API key"

In the top-right corner of the page, click the + New API key button. A small form opens.

Step 3: Fill in the details

• Name -- A label so you can recognize the key later. Use something descriptive like "Claude Desktop -- US Shop" or "ChatGPT for John". Names are visible only to you.
• Shop -- Choose a single shop, or leave the field on "All shops" to give the key access to every shop you have connected. Most users prefer one key per shop so each AI conversation is automatically scoped to the right data.
• Expires in -- How many days until the key automatically stops working. The default is 365 days. Shorter expiries are safer; longer expiries mean you don't have to rotate the key as often. You can revoke a key at any time regardless of its expiry.
• Allow dated COGS uploads -- Optional and available only to an owner/admin after selecting one shop. Leave this off for AI assistants and reporting integrations. Enable it only for a trusted server-side warehouse/ERP job.

Step 4: Click "Create key"

Dashboardly generates the key and displays it in a confirmation panel. The key is shown in full only this one time.

Step 5: Copy the key immediately

Click the Copy button to put the key on your clipboard. Paste it into a secure place (your assistant's configuration file, a password manager, or a safe note). If you close the panel without copying, you have to revoke the key and create a new one -- there is no way to retrieve it again.

Step 6: Connect your AI assistant

Open your AI assistant's settings and add Dashboardly as a connection (the exact path varies by assistant; see the next section for guidance on each one).

Step 7: Confirm the connection

Ask your assistant a simple question like "What's my net profit for last week?" If everything is set up correctly, the assistant responds with the answer pulled from your live Dashboardly data. If you see an error, see Why isn't my AI assistant working?.

Connecting an AI Assistant

The exact setup depends on which assistant you use. After you create the key in Dashboardly, the confirmation panel shows ready-to-paste configuration snippets for the most popular tools.

Claude (Desktop and Web)

In Claude's settings, look for a section called Connectors, Integrations, or MCP servers. Add Dashboardly and complete Dashboardly account sign-in. On the consent screen, choose all accessible shops, selected shops, or the current shop only. One OAuth connector can then work across the shops you authorized.

Developer tools such as Claude Code can instead use the API-key configuration shown in Dashboardly after key creation.

ChatGPT

In ChatGPT, open the Apps & Connectors menu and add Dashboardly as a custom connector. Complete Dashboardly account sign-in and choose the shop access you want to grant. ChatGPT remembers the connection across your conversations.

Cursor

In Cursor, open Settings > MCP, click Add new MCP server, and paste the Dashboardly endpoint and key. Cursor uses the connection while you code, so you can ask questions like "What's my best-selling SKU this month?" without leaving your editor.

Other AI assistants

Any assistant that speaks the Model Context Protocol can connect. Provide the assistant with the Dashboardly MCP endpoint URL and the API key (treat it like a password). The assistant should automatically discover what data is available.

What Your AI Assistant Can Do

Once connected, your assistant can answer questions across every major area of your shop data. You ask questions in plain English (or any language your assistant supports), and the assistant decides which data to pull.

The assistant cannot perform actions in your TikTok Shop or in Dashboardly. It can only read.

Order results include the TikTok order ID, timestamps, status, fulfillment, line-item SKU identifiers and Dashboardly's canonical signed financial fields. The default is the complete financial response; an integration can explicitly request the lightweight response when it only needs order identity and status. Buyer name, email, phone, postal address and tracking details are never returned.

The full read contracts currently cover Dashboard summary, Sales & Profit, Profit & Loss and its daily automation export, Cashflow (when enabled for the shop), Orders, Inventory, read-only Manual Adjustments and Warehouse configuration, customer summary/LTV and aggregate journeys/cohorts, refunds, geographic/hourly order analytics, and the listed Marketing views. Settings, Billing and agency administration do not have dedicated MCP tools because they are account-operational or mutable rather than shop analytics surfaces.

Managing Your Keys

Viewing keys

The Settings > API Keys page lists every key you have created with its name, the first few characters of the key (so you can recognize it), the shop it is bound to, when it was created, when it was last used, and when it expires.

Inspecting usage

Click any active key to expand a usage panel showing:

• Total calls in the last 30 days
• Success rate (calls that returned data successfully)
• Average response time so you know the connection is fast
• A daily activity chart for the last 7 days
• The most-used data tools so you can see what the assistant asks for most

This is useful for confirming that a key is being used, spotting unusual activity, or seeing what your assistant tends to focus on.

Revoking a key

If a key is lost, exposed, or no longer needed, click the Revoke icon next to it. Dashboardly immediately blocks any further requests using that key. AI assistants connected with the revoked key will see an error on their next question.

Revoking is instant. There is no grace period.

Key expiry

Each key has an expiry date set when you create it. Dashboardly shows a warning badge on the API Keys page when a key has 14 days or fewer remaining. Expired keys stop working automatically -- no need to revoke them.

To rotate a key on a recurring schedule, create a new key, update your AI assistant to use it, then revoke the old one.

Connected Apps

Some AI assistants, including ChatGPT and Claude Desktop, connect through Dashboardly account sign-in instead of requiring you to copy an API key. When you grant access, the assistant appears in the Connected Apps section at the bottom of the API Keys page. The connection shows whether it covers all accessible shops, selected shops, or the current shop only.

For each connected app you can see its name, shop scope, when it first connected, and when it was last active.

• Revoke immediately invalidates the connection's access and refresh tokens and blocks new sign-ins. Reconnect the app to choose a different shop scope.

Security & Privacy

API keys are sensitive. Treat each key like a password.

• Never commit a key to a public code repository. If you accidentally do, revoke it from Dashboardly and generate a new one.
• Never share a key in a chat message, email, or screenshot. Anyone with the key can read your data until you revoke it.
• Use one key per assistant or per device. That way, if a key is compromised on one device you can revoke just that key without disturbing your other connections.
• Set a sensible expiry. A key that expires in 90 days is safer than one that lasts forever. You can always create a new one.

Dashboardly never displays the full key after creation. The only place to find it is wherever you saved it when the key was generated.

All requests from AI assistants are made over HTTPS.

What we record, and what we never record. Dashboardly records request metadata on a best-effort basis: which key was used, which shop, which data area was queried, when, how long it took, whether it succeeded, the response size, and the calling IP address. You can review this history per-key from the usage panel described above.

Dashboardly does not log the questions you ask your assistant, the assistant's answers, or the request and response payloads. Those never reach the usage history.

Because the usage write is asynchronous and never allowed to fail a customer request, a call still succeeds even if its usage row does not get written. The usage panel is therefore operational telemetry for spotting unexpected activity — it is not a guaranteed-complete audit ledger, so do not treat a missing row as proof that a request did not happen.

This applies to the MCP connection described on this page. The private Developer REST API records the same kind of metadata under the same best-effort rules; see the Developer REST API article for its own details.

Default keys cannot change product costs, send a refund, or affect TikTok Shop. If you explicitly enable dated COGS uploads, that dedicated key can update Dashboardly costs only for its selected shop. Store it server-side, rotate it regularly, and revoke it immediately if it may have leaked.

Common Questions

Does my AI assistant see my whole Dashboardly account, or just one shop?

It depends on the scope you granted. An OAuth connector can use all shops you can currently access, only selected shops, or the current shop only. An API key can be merchant-wide or bound to one shop. Dashboardly re-checks live account and collaborator access on every OAuth request, so losing access to a shop also removes it from the connector.

Can I create different keys for different team members?

Yes. Create one named key per person ("Claude -- Maria", "ChatGPT -- John") and share each key only with the person who needs it. If someone leaves the team, revoke their key without affecting anyone else.

Will using an AI assistant cost me extra?

No. There is no per-query fee from Dashboardly. Your AI assistant provider (OpenAI, Anthropic, etc.) bills you separately for the assistant itself based on their own pricing.

How fresh is the data my assistant sees?

Exactly as fresh as what you see in Dashboardly. If the dashboard shows a metric updated 2 minutes ago, that is what the assistant gets. Settlement-based numbers (fees, taxes) may be estimated for very recent orders -- see Why is my data delayed? for the full story.

Can my AI assistant make changes to my shop?

No. MCP/report access remains read-only, and Dashboardly never writes to your TikTok Shop. Separately, an owner/admin can issue a dedicated, one-shop Developer API key carrying one or both of the v1 write permissions: dated COGS uploads and manual-adjustment management. Both write only into Dashboardly, never into TikTok Shop. Do not give such a key to an AI assistant; use it only from your trusted warehouse/ERP backend.

What happens to my old keys if I downgrade my plan?

If you downgrade to Brand Starter, all existing API keys stop working immediately. Re-upgrade to Brand Growing or higher to reactivate them, or create new keys after upgrading.

Can I see what my AI assistant has been asking?

Only which data areas it used, not the questions themselves. The usage panel for each key shows the most-used data areas (orders, P&L, top products, etc.) and a 7-day activity chart. We do not log the natural-language questions the user typed -- only which data tools the assistant called.