The :customer_id placeholder

:customer_id is how CustomerDashboard isolates data on a multi-customer dashboard. You write it in the widget SQL. The server replaces it with the current customer’s ID before the query reaches your database.

Viewers cannot edit the placeholder. They cannot pass a different ID. That is the whole point.

What to write

Use it anywhere a bound value is legal in your SQL dialect — usually in WHERE or JOIN:

SELECT product, SUM(quantity) AS units
FROM order_lines
WHERE client_id = :customer_id
GROUP BY product
ORDER BY units DESC

The column name on your side can be anything (client_id, account_id, tenant_id, org_slug). The placeholder name is always :customer_id.

The value comes from the customer record you created on the dashboard. It must match the values stored in your database.

What gets bound

If you run a query in the editor before a test customer ID or a real customer exists, the editor asks you to set one. The query cannot be previewed without a value to bind.

When you should omit it

Leave :customer_id out only when every customer should see the same rows — a shared benchmark, a public catalog, a company-wide announcement metric.

The editor shows a warning when a customer-dashboard query has no :customer_id. Read the warning. If the widget is supposed to be private, add the filter.

AI assistants connected through MCP are stricter: they cannot save a customer-dashboard widget without :customer_id unless you explicitly allow a shared query.

Google Sheets

Sheets widgets cannot bind :customer_id. Do not use Sheets for data that must differ per customer.

Checklist

1. The dashboard type is Customer.
2. Each customer has a customer ID that exists in the data.
3. Every private widget includes :customer_id.
4. You have previewed as at least two different IDs and the rows changed.

Related

• Multi-customer dashboards
• Customers
• Writing queries