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

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

<!-- agent-signals: reading_time_min: 7 · est_tokens: 2793 · updated: 2026-11-16 -->
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), [Get ad spend usage](/docs/api/store-data/usage-get-ad-spend.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.

By the end of this page you will:

1. **Sign in and create a workspace**
2. **Connect Google Ads, Merchant Center and your store** (where conversions go and orders come from)
3. **Create the conversion actions and add your costs** (so every order carries its profit)
4. **Check an order arrives**, then **ask Claude for a POAS report**

This is the [Quickstart](/docs/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](/docs/cli/overview#install-and-run).

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

## 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**. Link Merchant Center to that Google Ads account in Google first.



**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" }'
```

You should see `"status": "active"` and a `propertyId`: keep it. The feed setup is on [Merchant Center](/docs/using/merchant-center).



> **Warning:** **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](/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" }'
```

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

## 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>" }'
```

You should see `"status": "complete"` and eight actions `linked` as **secondary**: your campaigns don't change yet. For Meta, see [Meta](/docs/channels/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](/docs/using/costs)); under **Configure consent**, choose your banner ([Consent](/docs/using/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).

## 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).

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