Python SDK: send and verify conversions

plainrouter contains the generated Python SDK and the plainrouter command-line interface. The SDK exposes synchronous and asynchronous Conversion API operations, with ten convenience imports at the package root. The CLI exposes nine API commands. The current PyPI release is 0.6.0 and targets signed API contract 0.5.0. The source is in plainrouter/sdk.

Requirements

Python 3.11 or newer.
A Signals workspace secret.
Server-side code. Do not put the secret in browser or distributed client code.

Install

python -m pip install plainrouter==0.6.0

For terminal commands, follow the CLI quickstart for an isolated installation, authentication, and configuration. This page covers the Python application client.

Create a client

from plainrouter import create_client, list_events

client = create_client("YOUR_SIGNALS_WORKSPACE_SECRET")
response = list_events.sync(client=client)

The default API base is https://plainrouter.com/api/v1 and the default request timeout is 30 seconds.

Use async operations

Each operation module also provides an asynchronous method:

from plainrouter import create_client, get_event

client = create_client("YOUR_SIGNALS_WORKSPACE_SECRET")
response = await get_event.asyncio(
    event="event-id",
    client=client,
)

Send a Meta conversion

Send a server-side purchase through Plainrouter to your connected Meta destination. This is a Plainrouter SDK recipe, not a direct Meta Graph API tutorial. A successful create response confirms ingestion; inspect destination delivery separately. Before sending, confirm settlement on your server, load the order’s recorded advertising consent, and select the backend as the purchase owner. This request can create a real conversion. Use the sandbox for synthetic validation or a controlled destination test during setup.

Send a purchase synchronously

The example accepts an order mapping from your application:

Input	What to supply
`id`	Stable, non-personal order ID, unique within the workspace.
`paid_at`	Original purchase time as a timezone-aware Python `datetime`.
`total`, `currency`, `source_url`	Decimal-string amount, currency code, and actual checkout URL without personal data.
`consent`	Recorded `ad_storage`, `ad_user_data`, `ad_personalization`, `source`, and timezone-aware `captured_at`.
`email`, `phone`, `fbp`, `fbc`	Optional values you have permission to use; omit unavailable values.

The local consent check requires three recorded grants. It does not obtain consent or establish permission by itself. Do not replace an unknown decision with granted, or an old purchase or consent time with the current time.

from datetime import datetime, timezone
from http import HTTPStatus

from plainrouter import create_event
from plainrouter.generated.models import (
    CreateEventBodyType0,
    CreateEventResponse200,
    CreateEventResponse202,
)


def utc_time(value: datetime) -> str:
    if value.tzinfo is None or value.utcoffset() is None:
        raise ValueError("Purchase and consent times must include a timezone")
    return value.astimezone(timezone.utc).isoformat()


def purchase_event(order):
    if not isinstance(order["id"], str) or not order["id"].strip():
        raise ValueError("A stable order ID is required")
    consent = order["consent"]
    states = ("ad_storage", "ad_user_data", "ad_personalization")
    if any(consent.get(key) != "granted" for key in states):
        raise ValueError("Recorded advertising consent must permit this purchase")

    payload = {
        "event_id": f"purchase:{order['id']}",
        "event_name": "Purchase",
        "event_time": utc_time(order["paid_at"]),
        "event_source": order["source_url"],
        "action_source": "website",
        "consent_basis": "consent",
        "consent": {
            **{key: consent[key] for key in states},
            "captured_at": utc_time(consent["captured_at"]),
            "source": consent["source"],
        },
        "value_data": {
            "value": order["total"],
            "currency": order["currency"],
            "order_id": order["id"],
        },
    }
    for section, keys in (
        ("user_data", ("email", "phone")),
        ("click_ids", ("fbp", "fbc")),
    ):
        values = {key: order[key] for key in keys if order.get(key)}
        if values:
            payload[section] = values
    return CreateEventBodyType0.from_dict(payload)


def accepted_event(response):
    if response.status_code not in {HTTPStatus.OK, HTTPStatus.ACCEPTED}:
        raise RuntimeError(f"Create event returned HTTP {response.status_code}")
    if not isinstance(response.parsed, (CreateEventResponse200, CreateEventResponse202)):
        raise RuntimeError("Create event returned no recognized receipt")
    return response.parsed


def send_purchase(client, event):
    return accepted_event(create_event.sync_detailed(client=client, body=event))

Create the authenticated client once in your service, loading PLAINROUTER_SIGNAL_SECRET from your secret manager. After loading order from your database, build event = purchase_event(order) and call send_purchase(client, event). The returned receipt exposes event_id and duplicate; it is not a Meta delivery receipt. CreateEventBodyType0.from_dict constructs the published consented request model. It does not prove that input meets every server validation rule. Plainrouter normalizes and hashes supported raw identity fields before Meta delivery. Include only actual browser identifiers; see identifier formats.

Send the same model asynchronously

Reuse the same event model and receipt check in an async service:

async def send_purchase_async(client, event):
    response = await create_event.asyncio_detailed(client=client, body=event)
    return accepted_event(response)

Await send_purchase_async(client, event) from your application’s async context. The client reuses an httpx session. Reuse a client per service configuration and close it at shutdown; the generated client supports with for synchronous use and async with for asynchronous use.

Retry safely

Persist one payload per paid order before sending, including the event ID, original purchase time, amount and applicable consent snapshot. Reconstruct the generated model from that stored payload for a later job. Do not rebuild it with new timestamps or identity values. Recheck that advertising use is still permitted before retrying.

HTTP 202, duplicate: false: a new event was accepted for processing.
HTTP 200, duplicate: true: the event was already accepted. Inspect the original event; the retry does not update or enrich it.
A timeout or lost response leaves acceptance uncertain. Retry the same stored ID and payload rather than minting a new ID.

You can use the generated idempotency_key argument instead of a body event_id. When both are present, they must match. Your application owns durable job retries and concurrent-order guards; the SDK does not implement that workflow for you. A separate browser signalq("track", ...) call generates its own ID and cannot accept this recipe’s order ID. Choose one purchase owner, and avoid sending the same checkout through SDK, managed browser tracking and Stripe verified revenue. See event-ID deduplication.

Confirm Meta delivery

Use get_event.sync_detailed(client=client, event=receipt.event_id) for the receipt returned by send_purchase. Check HTTP 200 before reading its parsed event and deliveries. The async equivalent is get_event.asyncio_detailed. Import get_event from plainrouter. A delivery marked accepted confirms Meta acceptance. queued, sent and retrying are pending; an empty delivery list is not a success receipt. Follow delivery statuses and Meta troubleshooting for failed or skipped deliveries. Acceptance does not guarantee attribution.

Troubleshoot a purchase request

Symptom	What to do
Local consent or timezone error	Load the recorded decision and timezone-aware original times. Do not invent replacement values.
HTTP `401`	Stop automatic retries and check the Signals workspace secret. MCP tokens and browser publishable keys cannot authenticate this API.
HTTP `422`	Inspect the field errors in the detailed response. Check consent, decimal-string amounts and matching idempotency keys; redact identity and credentials before sharing diagnostics.
`httpx.TimeoutException` or a connection failure	Acceptance may be uncertain. Use a bounded retry of the same stored payload after checking consent.
Unexpected status or response parsing failure	Keep the original ID. Inspect the detailed HTTP result or the event resource before deciding whether to retry; do not count the request as confirmed ingestion.
Receipt exists but Meta has no event	Inspect the delivery trace and connected destination; repeating the create call is not a delivery replay.

Verify Signal ingestion

from plainrouter import create_client, verify_signal_ingestion

client = create_client("YOUR_SIGNALS_WORKSPACE_SECRET")
response = verify_signal_ingestion.sync(client=client)

The operation is idempotent. A repeated verification returns the existing event with duplicate: true. The event confirms ledger receipt but is not real arrival evidence and does not complete onboarding.

Available operation modules

Module	Purpose
`create_event`	Submit an idempotent conversion event.
`verify_signal_ingestion`	Write an identity-free ingestion diagnostic that does not complete onboarding.
`get_event`	Retrieve an event, lineage, and delivery state.
`list_events`	List recent events and delivery metrics.
`set_destination_test_mode`	Enable or disable destination test mode.
`send_test_purchase`	Send a controlled test purchase.
`replay_deliveries`	Replay eligible recent deliveries.
`get_reconciliation_report`	Retrieve reconciliation results for a date.
`get_emq_report`	Retrieve recent Event Match Quality snapshots.
`delete_user_data`	Delete data matching a hashed identifier.

List events by cursor

Cursor-based listing is available through the generated module rather than a package-root convenience import:

from plainrouter import create_client
from plainrouter.generated.api.operations import list_events_by_cursor

client = create_client("YOUR_SIGNALS_WORKSPACE_SECRET")
response = list_events_by_cursor.sync(client=client, per_page=25)

Omit cursor on the first request. For the next page, pass the opaque next_cursor returned in the response’s event pagination data. The CLI does not expose this operation.

Configure another API origin or timeout

Pass base_url or an httpx.Timeout when creating the client:

import httpx
from plainrouter import create_client

client = create_client(
    "YOUR_SIGNALS_WORKSPACE_SECRET",
    base_url="https://example.test/api/v1",
    timeout=httpx.Timeout(20.0),
)

Override the production origin only for a Plainrouter-provided region or a controlled test environment.

Handle credentials safely

The Python SDK accepts a Signals workspace secret. It does not accept an MCP workspace execution token or OAuth management credential. Keep the secret in a server-side secret manager. Never include it in prompts, URLs, logs, source control, or client-side code. For request and response fields, use the API reference.

Overview

SDKs

Recipes

Python SDK: send and verify conversions

Requirements

Install

Create a client

Use async operations

Send a Meta conversion

Send a purchase synchronously

Send the same model asynchronously

Retry safely

Confirm Meta delivery

Troubleshoot a purchase request

Verify Signal ingestion

Available operation modules

List events by cursor

Configure another API origin or timeout

Handle credentials safely

Implementation references

​Requirements

​Install

​Create a client

​Use async operations

​Send a Meta conversion

​Send a purchase synchronously

​Send the same model asynchronously

​Retry safely

​Confirm Meta delivery

​Troubleshoot a purchase request

​Verify Signal ingestion

​Available operation modules

​List events by cursor

​Configure another API origin or timeout

​Handle credentials safely

​Implementation references

Requirements

Install

Create a client

Use async operations

Send a Meta conversion

Send a purchase synchronously

Send the same model asynchronously

Retry safely

Confirm Meta delivery

Troubleshoot a purchase request

Verify Signal ingestion

Available operation modules

List events by cursor

Configure another API origin or timeout

Handle credentials safely

Implementation references