> ## Documentation Index
> Fetch the complete documentation index at: https://996f455-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://996f455-productmetrics.manicule.dev/docs/llms-full.txt (large).
> To search and read these docs as tools, connect the MCP server at https://996f455-productmetrics.manicule.dev/docs/api/mcp.
> Every agent surface: https://996f455-productmetrics.manicule.dev/docs/.well-known/llms-manifest.json

# Set the profit cost fallback and margin costs (/docs/api/stores-and-tracking/tracking-update-margin-policy)

<!-- agent-signals: reading_time_min: 7 · est_tokens: 3929 · updated: 2026-11-16 -->
Related: [Connect a store](/docs/api/stores-and-tracking/stores-connect.md), [New WooCommerce setup token](/docs/api/stores-and-tracking/stores-create-woocommerce-setup-claim.md), [Choose the store platform](/docs/api/stores-and-tracking/stores-select-platform.md), [Assign a store to a property](/docs/api/stores-and-tracking/tracking-assign-property.md), [Track a website](/docs/api/stores-and-tracking/tracking-create-website-installation.md), [Get store connections](/docs/api/stores-and-tracking/tracking-get-commerce-configuration.md)

> Saves the margin policy of one connected store (connectionId: tracking.get_configuration connections[].id), which tracking needs to report profit.

`PUT https://prod-backend.productmetrics.io/api/public/v1/companies/{companyId}/tracking/connections/{connectionId}/margin-policy`

**Scope** `setup` · **Access** Changes data · **Operation id** `tracking.update_margin_policy`

## Try it

`productmetrics` runs after `productmetrics login`; curl needs `PM_TOKEN` (see [Authentication](/docs/api/overview#authentication)). Set `$COMPANY_ID`, `$CONNECTION_ID` first.



**productmetrics CLI:**

```bash
# body.json holds the JSON body from the curl example
productmetrics tracking update-margin-policy \
  --company-id $COMPANY_ID \
  --connection-id $CONNECTION_ID \
  --body-file body.json \
  --auto-idempotency-key \
  --json
```

**curl:**

```bash
curl -X PUT "https://prod-backend.productmetrics.io/api/public/v1/companies/$COMPANY_ID/tracking/connections/$CONNECTION_ID/margin-policy" \
  -H "Authorization: Bearer $PM_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "expectedRevision": 0,
    "policy": {
      "schema_version": 2,
      "currency_code": "EUR",
      "valid_from": "2026-11-02T09:30:00.000Z",
      "product_cost_fallback": {
        "basis_points": 0
      },
      "non_product_cost_resolution": {
        "source": "product_metrics_default",
        "catalog_version": 1,
        "country_code": "NL"
      },
      "default_rules": {
        "outbound_shipping_micros": "108000000",
        "return_shipping_micros": "108000000",
        "pick_pack_base_micros": "108000000",
        "pick_pack_unit_micros": "108000000",
        "fulfillment_unit_micros": "108000000",
        "return_processing_unit_micros": "108000000",
        "external_payment_fixed_micros": "108000000",
        "external_payment_basis_points": 0
      },
      "country_rules": [
        {
          "country_code": "NL"
        }
      ],
      "value_loss_basis_points": {
        "RESTOCKED": 0,
        "NOT_RESTOCKED": 0
      }
    }
  }'
```

## Response

API response (200):

```json
{
  "data": {
    "policy_id": "6f1c2a7e-3b4d-4e8f-9a01-2c3d4e5f6a7b",
    "policy_revision": 1,
    "desired_revision": 1,
    "idempotency_key": "6f1c2a7e-3b4d-4e8f-9a01-2c3d4e5f6a7b",
    "changed": true
  },
  "request_id": "req_01JZGC2J8SE680Z2FPHJ14YPZ3"
}
```

**CLI output:** `productmetrics tracking update-margin-policy --json` prints `{ "ok": true, "data": …, "request_id": "…" }` with the same `data`.

## Before you call

`policy.product_cost_fallback.basis_points` is the product cost assumed when a product has no cost of goods, as a share of its price in basis points (3000 = 30%). The other fields are shipping, fulfilment, payment and return costs. The whole policy is sent and replaces the stored one, so read [`tracking.get_configuration`](/docs/api/stores-and-tracking/tracking-get-configuration) first and change only what the person asked for: start from the connection's entry in `marginPolicies` without `policy_id`, `connection_id`, `policy_revision` and `reported`, or, when it has none, build it from `marginDefaultCatalog` (null until the property's store scopes each have exactly one country and one currency: [`tracking.update_scope_dimensions`](/docs/api/stores-and-tracking/tracking-update-scope-dimensions), on the store's default scope too): `{schema_version: 2, currency_code, valid_from: <now, ISO 8601>, product_cost_fallback: {basis_points}, non_product_cost_resolution: {source: "product_metrics_default", catalog_version, country_code}, default_rules, country_rules: [], value_loss_basis_points}` (with `product_metrics_default`, `default_rules` and `value_loss_basis_points` stay as the catalog has them). `expectedRevision` is the configuration's `desiredRevision`; a stale one answers 409 `margin_policy_revision_conflict`: read again and resend. Send an Idempotency-Key header (a UUID); a retry with the same key returns the first save. Needs editor or admin access. Answers `policy_id`, `policy_revision`, the configuration's new `desired_revision` and `changed`.

## Path parameters

| Name           | Type          | Description                                                                                                                                                                                                     |
| -------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `companyId`    | string (uuid) | Your workspace id, from `productmetrics whoami` or [`properties.list`](/docs/api/account/properties-list) (`company_id`).                                                                                            |
| `connectionId` | string (uuid) | Saves the margin policy of one connected store (`connectionId`: [`tracking.get_configuration`](/docs/api/stores-and-tracking/tracking-get-configuration) `connections[].id`), which tracking needs to report profit. |

## Headers

| Name              | Type          | Required | Description                                                                                                        |
| ----------------- | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `Idempotency-Key` | string (uuid) | Yes      | A new UUID per intended change, the same one to retry it. Without it the API answers 400 idempotency_key_required. |

## Body

| Name                                                 | Type               | Required | Description                                                                                                                                                                      |
| ---------------------------------------------------- | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expectedRevision`                                   | integer            | Yes      | `expectedRevision` is the configuration's `desiredRevision`; a stale one answers 409 `margin_policy_revision_conflict`: read again and resend. At least 0.                       |
| `policy`                                             | object             | Yes      | The whole margin policy; it replaces the stored one. Start from the connection's `marginPolicies` entry, or from `marginDefaultCatalog` (see above).                             |
| `policy.schema_version`                              | number             | Yes      | Always `2`. Always `2`.                                                                                                                                                          |
| `policy.currency_code`                               | string             | Yes      | The currency of the cost amounts (ISO 4217, e.g. EUR).                                                                                                                           |
| `policy.valid_from`                                  | string (date-time) | Yes      | When the policy starts to apply (ISO 8601 date-time; send now for a new policy).                                                                                                 |
| `policy.product_cost_fallback`                       | object             | Yes      | The product cost assumed when a product has no cost of goods.                                                                                                                    |
| `policy.product_cost_fallback.basis_points`          | integer            | Yes      | That cost as a share of the product's price, in basis points (3000 = 30%), 0 to 10000. From 0 to 10000.                                                                          |
| `policy.non_product_cost_resolution`                 | object             | Yes      | Where the shipping, fulfilment, payment and return costs come from.                                                                                                              |
| `policy.non_product_cost_resolution.source`          | string             | Yes      | `product_metrics_default` (with `catalog_version` and `country_code` from `marginDefaultCatalog`) or `merchant_override`. One of `product_metrics_default`, `merchant_override`. |
| `policy.non_product_cost_resolution.catalog_version` | integer            | No       | Catalog version. Above 0.                                                                                                                                                        |
| `policy.non_product_cost_resolution.country_code`    | string             | No       | Country code.                                                                                                                                                                    |
| `policy.default_rules`                               | object             | Yes      | The shipping, fulfilment, payment and return costs. With `product_metrics_default`, keep them as the catalog has them.                                                           |
| `policy.default_rules.outbound_shipping_micros`      | string             | Yes      | Shipping cost per order, in micros of `currency_code` (a whole-number string; 1000000 = 1.00). Up to 20 characters.                                                              |
| `policy.default_rules.return_shipping_micros`        | string             | Yes      | Shipping cost per return, in micros of `currency_code` (a whole-number string; 1000000 = 1.00). Up to 20 characters.                                                             |
| `policy.default_rules.pick_pack_base_micros`         | string             | Yes      | Pick-and-pack cost per order, in micros of `currency_code` (a whole-number string; 1000000 = 1.00). Up to 20 characters.                                                         |
| `policy.default_rules.pick_pack_unit_micros`         | string             | Yes      | Pick-and-pack cost per item, in micros of `currency_code` (a whole-number string; 1000000 = 1.00). Up to 20 characters.                                                          |
| `policy.default_rules.fulfillment_unit_micros`       | string             | Yes      | Fulfilment cost per item, in micros of `currency_code` (a whole-number string; 1000000 = 1.00). Up to 20 characters.                                                             |
| `policy.default_rules.return_processing_unit_micros` | string             | Yes      | Return handling cost per returned item, in micros of `currency_code` (a whole-number string; 1000000 = 1.00). Up to 20 characters.                                               |
| `policy.default_rules.external_payment_fixed_micros` | string             | Yes      | Fixed payment fee per order, in micros of `currency_code` (a whole-number string; 1000000 = 1.00). Up to 20 characters.                                                          |
| `policy.default_rules.external_payment_basis_points` | integer            | Yes      | Payment fee as a share of the order, in basis points (0 to 10000). From 0 to 10000.                                                                                              |
| `policy.country_rules`                               | array of object    | Yes      | Shipping costs that differ by country; `[]` for none. Each rule sets `outbound_shipping_micros`, `return_shipping_micros` or both. At most 250. Up to 250 items.                 |
| `policy.country_rules[].country_code`                | string             | Yes      | The country the rule applies to (ISO 3166-1 alpha-2, e.g. NL), once per list.                                                                                                    |
| `policy.country_rules[].outbound_shipping_micros`    | string             | No       | Outbound shipping micros. Up to 20 characters.                                                                                                                                   |
| `policy.country_rules[].return_shipping_micros`      | string             | No       | Return shipping micros. Up to 20 characters.                                                                                                                                     |
| `policy.value_loss_basis_points`                     | object             | Yes      | The share of a returned item's value that is lost, in basis points. With `product_metrics_default`, keep it as the catalog has it.                                               |
| `policy.value_loss_basis_points.RESTOCKED`           | integer            | Yes      | Value lost on a return that goes back into stock, in basis points (0 to 10000). From 0 to 10000.                                                                                 |
| `policy.value_loss_basis_points.NOT_RESTOCKED`       | integer            | Yes      | Value lost on a return that does not go back into stock, in basis points (0 to 10000). From 0 to 10000.                                                                          |

## Errors

A failure answers with its HTTP status and `{ error: { code, message, details? }, request_id }`. Branch on `code` (stable, lower_snake); show `message` to the person. The CLI prints the same `error` with `"ok": false`.

```json
{
  "error": {
    "code": "insufficient_scope",
    "message": "This operation needs the setup scope; connect again and allow it.",
    "details": {
      "required_scope": "setup"
    }
  },
  "request_id": "req_01JCWDY6SK96WSJ756SWM4937J"
}
```

| Status | Code                              | When                                                                                                                                           |
| ------ | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | `invalid_request`                 | A path, query or body value does not match this page. `details.issues` lists each `location`, `path` and `message`.                            |
| 400    | `idempotency_key_required`        | No `Idempotency-Key` header with a UUID.                                                                                                       |
| 401    | `invalid_token`                   | The token is missing, expired or revoked: sign in again (`productmetrics login`). The `WWW-Authenticate` header says why.                      |
| 403    | `insufficient_scope`              | The token lacks the `setup` scope (`details.required_scope`): sign in again and allow it.                                                      |
| 404    | `not_found`                       | An id in the path does not exist, or the signed-in person cannot open it.                                                                      |
| 409    | `margin_policy_revision_conflict` | `expectedRevision` is the configuration's `desiredRevision`; a stale one answers 409 `margin_policy_revision_conflict`: read again and resend. |
| 429    | `rate_limited`                    | More than 600 requests a minute for this person: wait the `Retry-After` seconds (60) and retry.                                                |

[All Stores and tracking operations](/docs/api/stores-and-tracking)
