Skip to content
CLI

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.

You need

The CLI, a Google Ads client account, Merchant Center and your store.

Steps

Sign in, create a workspace, connect Google Ads and the store, create the conversion actions.

Result

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 with npx @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:

TermWhat it is
WorkspaceYour company (company_id): members, billing and store connections
PropertyOne Google Ads account in the workspace, with the store assigned to it (property_id)
Browser stepA 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 --json

Tokens 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> --json

You 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 --json

Other 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> --json

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: 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 --json

You 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.

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 --json

marginDefaultCatalog 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.

Where next