#Offline Conversions

Status: Planned. The POST /analytics/conversions method is being designed. This page records the agreed principles; the set of fields is provisional and will be finalized in OpenAPI 3.1.

Purpose: pass a payment or a won deal from your CRM and accounting system to Walker Formulation Academy, so that the platform links the money to a lead, a session, and an acquisition channel and calculates channel payback.

#Contents

1. Why it is needed
2. When to use it
3. Access
4. Request
5. Linking to a lead, a session, or an external identifier
6. Response
7. Errors
8. Examples
9. How conversions reach the reports
10. Notes
11. Open questions

#Why it is needed

Site counters see visits and requests, but not money: payment happens in the CRM, at the till, or on the bank account. Without it, the Walker Formulation Academy strategist knows how many leads a channel brought but not how much it earned. An offline conversion adds the missing "lead → payment" link and makes it possible to calculate channel payback.

In Overview, the funnel steps deals_created, deals_won, and revenue are built from the platform's CRM data. If your deals live in an external CRM, this method and Leads and CRM are the way to give the platform the same information. The rules by which conversions and platform deals are merged without double counting are in How conversions reach the reports.

#When to use it

#Access

Cell addresses: RU https://formula-cream.pro, EN https://wfacademy.org, ID https://wfacademy.id. The amount's currency matches the cell's market: RUB for RU, GBP for EN, IDR for ID (Cells and data).

#Request

Headers: Authorization, Content-Type: application/json, Idempotency-Key (Conventions).

Body (provisional)

At least one of lead_id, external_id, session_id is required. If several are given, priority follows the order lead_id, external_id, session_id (provisional).

{
  "conversion_id": "pay_48213_1",
  "type": "payment",
  "value": { "amount": "4990.00", "currency": "RUB" },
  "occurred_at": "2026-10-11T08:15:30Z",
  "external_id": "crm-48213",
  "properties": { "product": "emulsion-mastery" }
}

#Linking to a lead, a session, or an external identifier

If the lead or session is not found, the conversion is rejected with the code not_found; the platform does not create "dangling" conversions.

#Response

Success is 201 Created for a new conversion and 200 OK on a repeat with the same conversion_id. The method is not asynchronous: no operation object is returned, and the reports are recalculated after the response.

{
  "conversion_id": "pay_48213_1",
  "status": "attributed",
  "lead_id": "lead_EXAMPLE_01",
  "attribution": { "channel": "search", "basis": "form" },
  "created_at": "2026-10-11T08:16:02Z"
}

The response field names are provisional.

#Errors

The format is application/problem+json; the codes are in the error catalog.

#Examples

#curl

curl -X POST 'https://formula-cream.pro/api/public/v1/analytics/conversions' \
  -H 'Authorization: Bearer sap_ru_live_EXAMPLE0KEYI_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: pay_48213_1' \
  -d '{
    "conversion_id": "pay_48213_1",
    "type": "payment",
    "value": { "amount": "4990.00", "currency": "RUB" },
    "occurred_at": "2026-10-11T08:15:30Z",
    "external_id": "crm-48213"
  }'

#Python

import os, requests

response = requests.post(
    "https://wfacademy.org/api/public/v1/analytics/conversions",
    headers={
        "Authorization": f"Bearer {os.environ['API_KEY']}",
        "Idempotency-Key": "pay_48213_1",
    },
    json={
        "conversion_id": "pay_48213_1",
        "type": "payment",
        "value": {"amount": "49.00", "currency": "GBP"},
        "occurred_at": "2026-10-11T08:15:30Z",
        "external_id": "crm-48213",
    },
    timeout=5,
)
response.raise_for_status()

#How conversions reach the reports

The deals_won and revenue metrics in analytics (Reading analytics) come from the platform's CRM or from offline conversions, without double counting:

• a conversion with a lead_id whose platform CRM record already has a won deal replaces that deal's amount; if a lead has several conversions, the latest by occurred_at applies;
• a conversion for a lead with no won deal is added as a new won deal for the value amount;
• in the external and both CRM modes (modes) the same principle applies: the platform does not add a deal and a conversion for the same lead together.

A conversion also appears in the by-channel breakdown. The strategist uses it to calculate channel payback and to prioritize topics and advertising. Data does not appear in the reports instantly: the recalculation runs after receipt.

#Refunds

A refund is passed as a conversion with a negative amount in value.amount (for example, "-4990.00") and its own conversion_id. It reduces revenue for the period that contains the refund's occurred_at.

{
  "conversion_id": "refund_48213_1",
  "type": "payment",
  "value": { "amount": "-4990.00", "currency": "RUB" },
  "occurred_at": "2026-10-20T10:00:00Z",
  "external_id": "crm-48213"
}

#Notes

• Money is passed only as a string and only in the cell's currency; there is no currency conversion.
• A repeat with the same conversion_id is safe.
• Refunds are passed as a negative amount (Refunds).

#Open questions

1. Technical. The set and names of the request and response fields are provisional: the design specifies only the idea of "a payment or a deal tied to a lead/session".
2. For the owner. Multi-currency: whether it is acceptable to send an amount in a currency other than the cell's.
3. Technical. The maximum age window for occurred_at and the order of recalculating payback for late conversions; partial payments and amount adjustments (other than refunds).
4. For the owner. The analytics:write scope is shared with events; there is no separate permission for conversions (money data).