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.
This is the Quickstart for terminals, coding agents and scripts: each step shown with the productmetrics CLI, an AI assistant (MCP) and the public API. The example store is on Shopify.
The CLI, a Google Ads client account, Merchant Center and your store.
Sign in, create a workspace, connect Google Ads and the store, create the conversion actions.
Every order carries its profit, and Claude answers with a POAS report.
Prerequisites
- The CLI:
npm install -g @productmetrics/cli(Node.js 22 or later), or run it once withnpx @productmetrics/cli. See CLI overview. - Google Ads and Merchant Center: the client account that runs your campaigns, with Merchant Center linked to it in Google.
- Your store: Shopify in the examples; other platforms under Other store platforms.
Three terms used below:
| 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 |
Set it up
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.
You should see: "signed_in": true in productmetrics status --json.
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.
# 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>Manager (MCC) accounts are refused. Connect the client account that runs your campaigns.
You should see: "status": "active" and a propertyId: keep it. The feed setup is on Merchant Center.
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 --jsonOther platforms answer differently: see Other store platforms.
You should see: "mode": "redirect" and an authorizationUrl. Once the store is active, productmetrics tracking get-commerce-configuration --company-id <company_id> shows it.
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> --jsonThen 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: Costs and consent from the CLI.
You should see: "status": "complete" and eight actions linked as secondary: your campaigns don’t change yet. For Meta, see Meta.
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.
Costs and 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.
Other store platforms
Other platforms answer stores connect 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.