> ## Documentation Index
> Fetch the complete documentation index at: https://www.productmetrics.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> For every page in one file, fetch https://www.productmetrics.io/docs/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://www.productmetrics.io/docs/api/mcp.
> Every agent surface: https://www.productmetrics.io/docs/.well-known/llms-manifest.json

# Quickstart for developers and agents (/docs/cli/quickstart)

<!-- agent-signals: reading_time_min: 8 · est_tokens: 3164 · updated: 2026-11-17 -->
Related: [Product Metrics CLI](/docs/cli/overview.md), [CLI authentication](/docs/cli/authentication.md), [CLI commands](/docs/cli/commands.md), [Use the CLI from an AI agent](/docs/cli/for-agents.md), [JSON output and exit codes](/docs/cli/json-and-exit-codes.md)

> 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](/docs/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.

## Set it up with AI



Setting it up with AI takes one prompt and 60 seconds: paste it into your assistant.



First connect the Product Metrics MCP server ([https://www.productmetrics.io/mcp](https://www.productmetrics.io/mcp); see [Connect your assistant](/docs/mcp/connect)).

**Claude or ChatGPT:** "Set up Product Metrics for my store, from connecting the store to sending the first order to Google Ads. Check my setup status first, walk me through each open step, and give me the link when I need to click something."

**Claude Code or Codex:** "Set up Product Metrics for my store, from connecting the store to sending the first order to Google Ads, and give me the link when I need to click something. Use the Product Metrics MCP server, or the productmetrics CLI with --json and the Product Metrics skills if they are installed (run `productmetrics help agents` first)."

## Prerequisites

* **The CLI:** `npm install -g @productmetrics/cli` (Node.js 22 or later), or run it once with `npx @productmetrics/cli`. See [CLI overview](/docs/cli/overview#install-and-run).
* **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](#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](/docs/mcp/connect).



**CLI:**

```bash
productmetrics login            # add --no-browser on a machine without one
productmetrics status --json
```

**Claude / ChatGPT (MCP):**

```text
Add https://www.productmetrics.io/mcp as a custom connector,
sign in to Product Metrics and click Connect Claude (or your
app's name) on the consent page.
```

**API:**

```bash
# Every request carries a Product Metrics access token.
export PM_TOKEN="<access token>"
curl "https://prod-backend.productmetrics.io/api/public/v1/onboarding" \
  -H "Authorization: Bearer $PM_TOKEN"
```

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.



**CLI:**

```bash
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
```

**Claude / ChatGPT (MCP):**

```text
"Create a workspace called My Shop and tell me what's left."
→ calls execute: onboarding.set_account_type, onboarding.complete,
  companies.create, then setup.get_status
```

**API:**

```bash
curl -X PUT "https://prod-backend.productmetrics.io/api/public/v1/onboarding/account-type" \
  -H "Authorization: Bearer $PM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "account_type": "direct_advertiser" }'
curl -X POST "https://prod-backend.productmetrics.io/api/public/v1/onboarding/complete" \
  -H "Authorization: Bearer $PM_TOKEN"
curl -X POST "https://prod-backend.productmetrics.io/api/public/v1/companies" \
  -H "Authorization: Bearer $PM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "name": "My Shop" }'
```

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



**CLI:**

```bash
# 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>
```

**Claude / ChatGPT (MCP):**

```text
"Connect my Google Ads account and Merchant Center 123456789."
→ calls execute: the connect link first, then the
  property connection and the Merchant Center connection
```

**API:**

```bash
curl -X POST "https://prod-backend.productmetrics.io/api/public/v1/companies/<company_id>/google-ads/property-connections" \
  -H "Authorization: Bearer $PM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "connection_mode": "user_oauth", "customer_id": "1234567890" }'
```



> **Warning:** **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](/docs/using/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](/docs/platforms/shopify#in-the-app)).



**CLI:**

```bash
productmetrics stores connect \
  --company-id <company_id> \
  --provider shopify \
  --auto-idempotency-key --json
```

**Claude / ChatGPT (MCP):**

```text
"Connect my Shopify store to Product Metrics."
→ calls execute (POST /companies/{companyId}/stores)
  and gives you the Shopify link
```

**API:**

```bash
curl -X POST "https://prod-backend.productmetrics.io/api/public/v1/companies/<company_id>/stores" \
  -H "Authorization: Bearer $PM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "provider": "shopify" }'
```

Other platforms answer differently: see [Other store platforms](#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.



> **Warning:** **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).



**CLI:**

```bash
productmetrics google-ads create-conversion-actions \
  --property-id <property_id> \
  --company-id <company_id> --json
```

**Claude / ChatGPT (MCP):**

```text
"Create the Product Metrics conversion actions in Google Ads."
→ calls execute: google_ads.create_conversion_actions
```

**API:**

```bash
curl -X POST "https://prod-backend.productmetrics.io/api/public/v1/properties/<property_id>/google-ads/conversion-actions" \
  -H "Authorization: Bearer $PM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "company_id": "<company_id>" }'
```

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](/docs/using/costs)); under **Configure consent**, choose your banner ([Consent](/docs/using/consent)).

From the CLI: [Costs and 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](/docs/channels/meta).

### 6. Check an order arrives

Place a test order, then read the newest one. `productmetrics tracking get-configuration` gives the `storefront_scope_id`.



**CLI:**

```bash
productmetrics orders list \
  --company-id <company_id> \
  --storefront-scope-id <scope_id> \
  --limit 1 --json
```

**Claude / ChatGPT (MCP):**

```text
"I just placed a test order. Did Product Metrics receive it,
with its profit?"
→ calls execute: tracking.get_configuration, then orders.list
```

**API:**

```bash
curl "https://prod-backend.productmetrics.io/api/public/v1/companies/<company_id>/orders?storefront_scope_id=<scope_id>&limit=1" \
  -H "Authorization: Bearer $PM_TOKEN"
```

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



**Claude / ChatGPT (MCP):**

```text
"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)
```

**Claude Code:**

```bash
claude mcp add --transport http product-metrics \
  https://www.productmetrics.io/mcp
# then run /mcp in Claude Code and choose Authenticate
```

**You should see:** ROAS, POAS and profit after ads per campaign, plus products below break-even. To bid on profit, see [POAS bidding](/docs/features/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:

```bash
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](/docs/api/stores-and-tracking/tracking-update-margin-policy).

## Other store platforms

Other platforms answer `stores connect` differently (a setup token or a developer install): see their [platform guides](/docs/platforms/overview). 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](/docs/using/billing)). Checkout refuses with `needs_store_setup` until a platform is chosen.

## Where next



* [How it works](/docs/concepts/how-it-works): from paid order to conversion action.
* [Google Ads](/docs/channels/google-ads): consent, Data Manager access and Enhanced Conversions.
* [CLI for agents](/docs/cli/for-agents): `--json`, exit codes and driving `productmetrics` from an agent.
* [MCP tools](/docs/mcp/tools): every tool your assistant can call.
