Skip to content
Stores and tracking

Set the profit cost fallback and margin costs

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

PUT /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). Set $COMPANY_ID, $CONNECTION_ID first.

# 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

Response

API response (200):

{
  "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 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, 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

NameTypeDescription
companyIdstring (uuid)Your workspace id, from productmetrics whoami or properties.list (company_id).
connectionIdstring (uuid)Saves the margin policy of one connected store (connectionId: tracking.get_configuration connections[].id), which tracking needs to report profit.

Headers

NameTypeRequiredDescription
Idempotency-Keystring (uuid)YesA new UUID per intended change, the same one to retry it. Without it the API answers 400 idempotency_key_required.

Body

NameTypeRequiredDescription
expectedRevisionintegerYesexpectedRevision is the configuration’s desiredRevision; a stale one answers 409 margin_policy_revision_conflict: read again and resend. At least 0.
policyobjectYesThe whole margin policy; it replaces the stored one. Start from the connection’s marginPolicies entry, or from marginDefaultCatalog (see above).
policy.schema_versionnumberYesAlways 2. Always 2.
policy.currency_codestringYesThe currency of the cost amounts (ISO 4217, e.g. EUR).
policy.valid_fromstring (date-time)YesWhen the policy starts to apply (ISO 8601 date-time; send now for a new policy).
policy.product_cost_fallbackobjectYesThe product cost assumed when a product has no cost of goods.
policy.product_cost_fallback.basis_pointsintegerYesThat 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_resolutionobjectYesWhere the shipping, fulfilment, payment and return costs come from.
policy.non_product_cost_resolution.sourcestringYesproduct_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_versionintegerNoCatalog version. Above 0.
policy.non_product_cost_resolution.country_codestringNoCountry code.
policy.default_rulesobjectYesThe shipping, fulfilment, payment and return costs. With product_metrics_default, keep them as the catalog has them.
policy.default_rules.outbound_shipping_microsstringYesShipping cost per order, in micros of currency_code (a whole-number string; 1000000 = 1.00). Up to 20 characters.
policy.default_rules.return_shipping_microsstringYesShipping 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_microsstringYesPick-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_microsstringYesPick-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_microsstringYesFulfilment 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_microsstringYesReturn 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_microsstringYesFixed 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_pointsintegerYesPayment fee as a share of the order, in basis points (0 to 10000). From 0 to 10000.
policy.country_rulesarray of objectYesShipping 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_codestringYesThe country the rule applies to (ISO 3166-1 alpha-2, e.g. NL), once per list.
policy.country_rules[].outbound_shipping_microsstringNoOutbound shipping micros. Up to 20 characters.
policy.country_rules[].return_shipping_microsstringNoReturn shipping micros. Up to 20 characters.
policy.value_loss_basis_pointsobjectYesThe 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.RESTOCKEDintegerYesValue 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_RESTOCKEDintegerYesValue 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.

{
  "error": {
    "code": "insufficient_scope",
    "message": "This operation needs the setup scope; connect again and allow it.",
    "details": {
      "required_scope": "setup"
    }
  },
  "request_id": "req_01JCWDY6SK96WSJ756SWM4937J"
}
StatusCodeWhen
400invalid_requestA path, query or body value does not match this page. details.issues lists each location, path and message.
400idempotency_key_requiredNo Idempotency-Key header with a UUID.
401invalid_tokenThe token is missing, expired or revoked: sign in again (productmetrics login). The WWW-Authenticate header says why.
403insufficient_scopeThe token lacks the setup scope (details.required_scope): sign in again and allow it.
404not_foundAn id in the path does not exist, or the signed-in person cannot open it.
409margin_policy_revision_conflictexpectedRevision is the configuration’s desiredRevision; a stale one answers 409 margin_policy_revision_conflict: read again and resend.
429rate_limitedMore than 600 requests a minute for this person: wait the Retry-After seconds (60) and retry.

All Stores and tracking operations