Quickstart for developers and agents
Set up Product Metrics end to end from the productmetrics CLI, an AI assistant (MCP) or the public API, then ask for a POAS report.
By the end of this page you will:
- Sign in and create a workspace
- Connect Google Ads, Merchant Center and your store (where conversions go and orders come from)
- Create the conversion actions and add your costs (so every order carries its profit)
- Check an order arrives, then ask Claude for a POAS report
This is the Quickstart for terminals, coding agents and scripts. The example store is on Shopify.
| Term | What it is |
|---|---|
| Workspace | Your company (company_id): members, billing and store connections |
| Property | One Google Ads account in the workspace, with the store assigned to it (property_id) |
| Browser step | A step only a person can finish: productmetrics prints the URL and exits 4 |
Install the CLI with npm install -g @productmetrics/cli (Node.js 22 or later), or run it once with npx @productmetrics/cli. See CLI overview.
1. Sign in
productmetrics login signs you in through the browser. Your assistant signs in when you add the MCP server.
productmetrics login # add --no-browser on a machine without one
productmetrics status --jsonTokens last one hour and renew for 30 days.
2. Create a workspace
Save your account type and complete onboarding first: creating a workspace needs both. The idempotency key makes a retry return the same workspace, not a second one. Then read the setup status: it names the next step, so run it again after every step.
productmetrics onboarding set-account-type --account-type direct_advertiser --json
productmetrics onboarding complete --json
productmetrics companies create --name "My Shop" --auto-idempotency-key --json
productmetrics setup get-status --company-id <company_id> --jsonYou should see the new companyId (keep it), then journey_stage: "needs_property" and the next step in hub.company.next_action.
3. Connect Google Ads and Merchant Center
Google access is a browser step: the ads scope covers Google Ads and Merchant Center in one consent. Connecting the Google Ads account then creates the property. Link Merchant Center to that Google Ads account in Google first.
# prints the URL and exits 4: open it and approve on Google's screen
productmetrics google get-connect-link --scope ads --json
productmetrics google-ads list-accounts --json
productmetrics google-ads create-property-connection \
--company-id <company_id> \
--connection-mode user_oauth \
--customer-id 1234567890 --json
productmetrics merchant-center create-connection \
--property-id <property_id> --merchant-id <merchant_id>You should see "status": "active" and a propertyId: keep it. The feed setup is on Merchant Center.
Manager (MCC) accounts are refused. Connect the client account that runs your campaigns.
4. Connect your store
For Shopify, stores connect returns a Shopify App Store link and exits 4. Install and approve the app, link the store to your workspace, then switch on the app embed (exact clicks).
productmetrics stores connect \
--company-id <company_id> \
--provider shopify \
--auto-idempotency-key --jsonYou should see "mode": "redirect" and an authorizationUrl. Once the store is active, productmetrics tracking get-commerce-configuration --company-id <company_id> shows it.
Other platforms answer differently (a setup token or a developer install): see their platform guides. Outside Shopify, choose the store platform first with productmetrics stores select-platform --company-id <company_id> --platform woocommerce, then start the subscription with productmetrics billing create-checkout-link (Billing). Checkout refuses with needs_store_setup until a platform is chosen.
5. Create the conversion actions and add your costs
Product Metrics creates eight conversion actions in Google Ads: revenue and profit for orders, new customers, returning customers and LTV. This needs an active store and a workspace admin.
Until the store’s additional costs are saved, the profit actions stay empty. Save them in the app or with productmetrics tracking update-margin-policy (below).
productmetrics google-ads create-conversion-actions \
--property-id <property_id> \
--company-id <company_id> --jsonYou should see "status": "complete" and eight actions linked as secondary: your campaigns don’t change yet. For Meta, see Meta.
Then save the costs and choose your consent banner. In the app, open Tracking: under Add your additional costs, check the defaults and select Activate additional costs (Costs); under Configure consent, choose your banner (Consent).
From the CLI, read the configuration first: the store’s connections[].id, its marginPolicies or marginDefaultCatalog, desiredRevision and the installation’s features. tracking update-margin-policy replaces the whole policy, and tracking update-installation-features sets the consent manager (--cmp-adapter) with the other features:
productmetrics tracking get-configuration \
--company-id <company_id> --property-id <property_id> --json
# policy.json: the connection's policy, or one built from marginDefaultCatalog
productmetrics tracking update-margin-policy \
--company-id <company_id> \
--connection-id <connection_id> \
--expected-revision <desiredRevision> \
--policy "$(cat policy.json)" \
--auto-idempotency-key --jsonmarginDefaultCatalog is null until each store scope has exactly one country and one currency: set them with productmetrics tracking update-scope-dimensions (a WooCommerce store on plugin 1.0.12 or later sends them when it pairs). Every field, with the policy’s shape: Set the profit cost fallback and margin costs.
6. Check an order arrives
Place a test order, then read the newest one. productmetrics tracking get-configuration gives the storefront_scope_id.
productmetrics orders list \
--company-id <company_id> \
--storefront-scope-id <scope_id> \
--limit 1 --jsonYou should see order #1042 with revenueMicros: "108000000" (€108.00), margin.contributionMarginMicros: "48460000" (€48.46) and classification: "NEW". For a website on Cloudflare Tracking, use productmetrics tracking get-last-purchase with --company-id and --installation-id instead.
7. Ask Claude for a POAS report
Your assistant reads live Google Ads data joined with your margins and stock.
"What was my POAS per campaign over the last 30 days,
and which products lose money after ads?"
→ calls list_properties, then get_poas_report (level: campaign),
then get_poas_report (level: product, only_unprofitable: true)You should see ROAS, POAS and profit after ads per campaign, plus products below break-even. To bid on profit, see POAS bidding.