Track purchases, browser consent, and Stripe revenue

Use signalq to pass your consent platform’s current decision to Signals and send business events after a full advertising grant. With a connected Meta dataset, one browser track call supplies the managed Pixel and server event with a shared ID.

Before you begin

Install the generated Signals pixel once and keep its init call before consent and event calls.
Choose a consent source: a supported external signal, an explicit CMP adapter, or the configured Plainrouter fallback card. Verify the actual advertising choices on every page and after changes.
Connect Meta if you want managed Meta delivery.
Choose whether the browser, your backend, or Stripe owns each purchase. Follow Avoid duplicate Meta events before combining integrations.

Calls made before the asynchronous Signals script loads are queued, but the queue stub returns undefined. It does not return the later command’s result. Run examples that read an event ID, identification result, or visitor ID only after the generated script’s load event; register that handler before the script can finish loading. Do not install a second snippet to wait for it. The current v4 snippet sends its arrival first, then uses a queued explicit signalq("consent", …) decision when present. Otherwise it checks supported TCF and Consent Mode signals during a 1.5-second detection window. A detected supported CMP without a usable decision suppresses the fallback; it does not grant consent. Keep the explicit adapter below when your CMP needs one. If no external source takes precedence, the snippet can restore the saved Plainrouter choice or display the enabled fallback consent card. Accept all, Reject all, and Customize record different decisions. In Customize, Analytics controls ad_storage, while Marketing controls both ad_user_data and ad_personalization. Advertising events and managed Meta delivery still require all three grants; selecting only Analytics is insufficient. A later valid external decision dismisses the fallback. The pr_consent cookie stores the Plainrouter choice; it is separate from visitor measurement identifiers. To reopen the card from your own preferences control, use:

window.plainrouter("consent", "open");

This command opens the supported consent surface; it does not itself grant permission. Call it after the snippet loads and wire it to a visitor action. The fallback remains subject to its configured enablement and market policy. Set its banner and floating reopen options in Signals → Install. Use Cookie scan to check unrelated pre-consent scripts, and Consent choices to read recorded decisions when available. For verification, use a fresh browser context: test full acceptance, rejection, a partial Customize choice, a returning saved choice and withdrawal. Check actual event requests and destination delivery, not just whether a card appeared. A blocked config request or detected CMP without a decision can leave advertising events silent. Do not turn that unknown state into a grant. Connect signalq to your consent-management platform. Send the current advertising consent state after initialization and whenever the visitor changes it.

await signalq("consent", {
  consent_basis: "consent",
  consent: {
    ad_storage: "granted",
    ad_user_data: "granted",
    ad_personalization: "granted",
    captured_at: new Date().toISOString(),
    source: "your_cmp"
  }
});

// If the visitor later withdraws consent:
await signalq("consent", {
  consent_basis: "consent",
  withdrawn: true
});

Each permission accepts granted, denied, or unknown. Missing or unrecognized permissions remain unknown; Plainrouter never upgrades them to a grant. You can provide one or more supported consent adapters:

Input	Use
`consent`	Send Plainrouter’s explicit three-permission snapshot.
`consent_mode`	Map Google Consent Mode v2 fields.
`tcf`	Map a TCF v2 string and optional capture time.

When you provide more than one adapter, their derived permission states must agree.

Do not infer consent. Leave each permission unknown until your consent-management platform has an explicit choice.

Conversion events, visitor-cookie access, identity transmission, and managed Meta delivery require all three permissions to be granted. Granting ad_storage alone is insufficient. The identity-free arrival sent once at document initialization is a separate request and does not wait for these permissions. See What happens on initialization. A complete grant creates or refreshes the first-party identifiers used for session joins and eligible destination delivery. Leaving full consent stops event transmission and clears the current page’s consent-dependent identifiers. Explicit storage denial or withdrawal also discards the in-memory landing context. Send the latest structured state whenever the visitor’s choice changes. On a returning page, the arrival is sent while your consent platform restores its decision. Plainrouter does not read visitor cookies or send conversion events during that undecided period. Existing cookies are not read or refreshed merely because the snippet initialized.

Connect Cookiebot callbacks

Install Cookiebot on the same page. This adapter uses Cookiebot’s consent properties and browser events. Use it only when your configured marketing choice covers all three Plainrouter advertising permissions. For separate choices, map each permission individually with the structured snapshot above. Place this code once after your generated init call. It handles an already-restored choice and later CMP events. Automatic or implied consent stays unknown; only an explicit response can grant permissions.

function syncCookiebotConsent() {
  const cmp = window.Cookiebot;
  const explicit = cmp?.hasResponse === true &&
    cmp.consent?.method === "explicit";
  const marketing = cmp?.consent?.marketing;
  const permission = explicit && typeof marketing === "boolean"
    ? (marketing ? "granted" : "denied")
    : "unknown";

  window.signalq("consent", {
    consent_basis: "consent",
    consent: {
      ad_storage: permission,
      ad_user_data: permission,
      ad_personalization: permission,
      captured_at: new Date().toISOString(),
      source: "cookiebot_marketing"
    }
  });
}

for (const event of [
  "CookiebotOnConsentReady",
  "CookiebotOnAccept",
  "CookiebotOnDecline"
]) {
  window.addEventListener(event, syncCookiebotConsent);
}
syncCookiebotConsent();

captured_at records when this adapter reads the current decision. Retain your CMP’s consent record separately. Do not replay purchases from these callbacks: restored consent and multiple CMP events can call the adapter more than once. For a custom withdrawal button, notify Signals immediately as well as withdrawing in Cookiebot. Attach this function to your site’s existing consent-withdrawal control:

function withdrawAdvertisingConsent() {
  window.signalq("consent", {
    consent_basis: "consent",
    withdrawn: true
  });
  window.Cookiebot.withdraw();
}

Keep the consent bridge running when consent is denied so it can report changes. Check your CMP’s script-blocking configuration if callbacks never reach Signals. Use a development or test site and inspect its Network panel. Test the installed library, not just the pre-load queue. A successful arrival is a separate initialization check and can appear in every row below.

Current choice	Expected Signals behavior
CMP not ready, missing permissions, or implied choice in the Cookiebot adapter	No conversion transmission; `track` resolves to `null`.
All three advertising permissions granted	Consented `PageView` on entering a grant; subsequent `track` calls can reach the collector.
`ad_storage: "granted"`, with `ad_user_data` or `ad_personalization` denied or unknown	No conversion transmission. A storage grant alone is insufficient.
Full grant followed by denial or withdrawal	New conversions stop; consent-dependent in-flight work is cancelled. This cannot recall requests already received by a destination.
Returning page with a stored explicit grant	Arrival runs during initialization; conversions wait for the CMP to restore and report the grant.

For a CMP with separate permissions, exercise a partial choice through its UI and confirm the transmitted snapshot preserves it. Do not replace partial choices with the Cookiebot adapter’s shared marketing value. If the result differs, confirm init ran first, inspect the actual three permission values, and check for conflicting adapters. Use Verify ingestion to separate a collection problem from consent gating; use Meta delivery checks for destination acceptance.

How landing click IDs are handled

The snippet captures supported landing query parameters in the current document’s memory: fbclid, gclid, gbraid, wbraid, ttclid, and msclkid. Unknown or partial consent keeps this temporary buffer available for a later complete grant. Explicit storage denial or withdrawal discards it. Click IDs are sent with eligible events only after full consent. They never enter the identity-free arrival payload. The browser no longer reads or writes the legacy pr_click_ids value; it expires that cookie when full consent opens and when an active grant is withdrawn. A new document starts with its own landing context. The Meta _fbc and _fbp cookies are separate from this retired click-ID map and remain subject to full consent. At event intake, Plainrouter drops invalid or unsupported click-ID entries individually while retaining valid entries. Do not rely on one malformed value to reject an otherwise valid event.

Track an event

Call track with an event name and an optional payload:

const eventId = await signalq("track", "purchase", {
  value: "49.00",
  currency: "EUR",
  order_id: "ORDER-1042",
  num_items: 2
});

After the library loads, the promise normally resolves to the event ID after a successful collector response. If page exit switches delivery to a beacon, the ID can be returned without a collector acknowledgement. Check ingestion and destination delivery separately. It resolves to null when full consent is absent, consent changes stop the request, or collection is not accepted after the permitted attempts. Invalid calls, such as a missing event name or a call before init, can reject the promise. The public track command generates its own event ID. An event_id in the payload or an extra positional argument does not override it. order_id is purchase data, not the deduplication key.

Send monetary value as a decimal string, such as "49.00". This avoids floating-point ambiguity.

Standard event names

Common names are normalized to Meta’s standard spelling. For example, page_view becomes PageView and initiate_checkout becomes InitiateCheckout. Frequently used standard events include:

PageView
ViewContent
Search
AddToCart
AddToWishlist
InitiateCheckout
AddPaymentInfo
Purchase
Lead
CompleteRegistration
Contact
Schedule
Subscribe

Custom event names are trimmed and otherwise preserved.

Payload fields

These convenience fields move into the event’s value data automatically:

Field	Purpose	Example
`value`	Monetary value as a decimal string.	`"49.00"`
`currency`	ISO 4217 currency code.	`"EUR"`
`order_id`	Your unique order or transaction reference.	`"ORDER-1042"`
`contents`	Products or items associated with the event.	`[{ id: "SKU-1", quantity: 2 }]`
`num_items`	Total item count.	`2`

You can also provide a value_data object directly. Other custom fields remain on the event and are available to supported destinations.

Identify a consenting visitor

Call identify only after your consent policy permits advertising identity use:

const identified = await signalq("identify", {
  email: " Buyer@Example.com ",
  phone: "+358 (40) 123-4567"
});

The browser normalizes and SHA-256 hashes the values before sending them. Plainrouter never sends the raw email or phone in the identity request.

Email is trimmed and lowercased.
International phone numbers must start with + and include 8–15 digits after normalization.
Finnish local numbers require defaultPhoneRegion: "FI" in the initialization configuration.
Identification returns false on an insecure page where browser cryptography is unavailable.

<script>
  window.signalq = window.signalq || function () {
    (window.signalq.q = window.signalq.q || []).push(arguments);
  };
  signalq("init", {
    key: "YOUR_PUBLISHABLE_KEY",
    defaultPhoneRegion: "FI"
  });
</script>

Read the visitor ID

getVisitorId returns the current first-party visitor ID after consent is granted. It returns null while consent is pending or denied.

const visitorId = signalq("getVisitorId");

For a custom backend integration, a visitor ID alone is not an advertising consent grant. Follow the server-event recipe and preserve the actual consent decision. The Stripe verified-revenue adapter below does not use checkout metadata to establish an attributed visitor join.

Verify Stripe Checkout settlement

Stripe verified revenue records paid Checkout Sessions in Plainrouter. This is a revenue connection, not a Meta Conversions API integration: do not expect metadata.visitor_id to join the purchase to a browser visit or trigger Meta delivery. For consented advertising conversions, use the managed browser purchase or backend recipe.

What do I need before connecting Stripe?

You need an active Signals workspace, workspace-owner access to Connections, and permission to configure webhook endpoints for the Stripe account that receives your customers’ payments. Your application must already create Checkout Sessions and handle order fulfillment. This connection is separate from paying for Plainrouter. The supported settlement flow uses Checkout Session events. It does not establish support for every Stripe payment flow or recurring invoice event. Stripe’s fulfillment guide explains delayed payments and why returning to a success URL does not prove payment.

Configure the webhook

Open Connections → Revenue sources → Stripe.
Copy the workspace’s Webhook endpoint and add it as an endpoint in the intended Stripe account.
Subscribe to checkout.session.completed, checkout.session.async_payment_succeeded, and checkout.session.async_payment_failed. Add refund.created and charge.refunded if you track refunds.
Copy that endpoint’s signing secret into Endpoint signing secret in Plainrouter and choose Save secret. This is the webhook signing secret, not your Stripe API key.
Confirm the Stripe card shows connected. That status confirms a signing secret is configured; verify a settled payment separately below.

Plainrouter clears the secret field after saving. Use Rotate secret when replacing the endpoint’s signing secret. Remove secret stops webhook authentication until you save a replacement; it does not remove the endpoint from Stripe.

Associate a Checkout Session with your order

Set metadata.order_id to your application’s non-personal order ID when creating the Session on your server. Use the same order ID as your browser purchase if both sources report that order. Plainrouter trims this value and uses it as the purchase’s order ID; without it, the Checkout Session ID is the fallback. client_reference_id does not select Plainrouter’s order ID. Keep order IDs within 128 characters so they remain readable. This request calls Stripe directly, not the Plainrouter SDK. It creates a hosted, one-time Checkout Session. Set the variables from trusted server configuration and an existing order: select the Stripe Price on your server and persist one idempotency key for that checkout attempt. Reuse the key only when retrying the same request. Keep the Stripe secret key server-side.

curl https://api.stripe.com/v1/checkout/sessions \
  --user "$STRIPE_SECRET_KEY:" \
  --header "Idempotency-Key: $CHECKOUT_ATTEMPT_KEY" \
  --data-urlencode "mode=payment" \
  --data-urlencode "line_items[0][price]=$STRIPE_PRICE_ID" \
  --data-urlencode "line_items[0][quantity]=1" \
  --data-urlencode "metadata[order_id]=$ORDER_ID" \
  --data-urlencode "success_url=https://shop.example/checkout/success" \
  --data-urlencode "cancel_url=https://shop.example/cart"

Replace the example return URLs with your application’s URLs. Store the returned Session id alongside your order and redirect the customer to its url. See Stripe’s Create a Checkout Session reference for the complete request. Session creation and the success-page redirect are not payment verification.

How do I verify a settled purchase?

Inspect the endpoint’s delivery in Stripe for a known Checkout Session, then compare the order and amount with Signals. Plainrouter records revenue only when the settlement event has payment_status exactly paid.

Stripe state	Expected result
`checkout.session.completed`, `paid`	Records the paid Checkout Session.
`checkout.session.completed`, `unpaid`	No purchase yet; the response reports `pending: true` and `reason: "payment_pending"`.
`checkout.session.async_payment_succeeded`, `paid`	Records the settled purchase.
`checkout.session.async_payment_failed`	No purchase or refund; reason is `async_payment_failed`.
`no_payment_required`	No revenue event; reason is `no_payment_required`.
Missing or unknown payment status	No purchase; reason is `unverified_payment_status`.

An illustrative paid-webhook response is:

{
  "received": true,
  "event_id": "stripe_checkout:cs_example",
  "duplicate": false
}

Use the returned event_id to find the retained record through GET event. For this revenue flow, the check is the purchase record and value, not a Meta accepted delivery. A 404 can mean the wrong workspace or that the record is outside read retention. Duplicate paid notifications for the same Session reuse one purchase record and return duplicate: true. The first recorded purchase uses its settlement-confirming webhook’s time. An older duplicate can return duplicate: true without an event_id; do not create another purchase to force a receipt or recover expired payload data. Supported refund notifications record an idempotent negative revenue adjustment. Plainrouter first tries the saved PaymentIntent-to-purchase link in this workspace, then available order metadata and charge references. Purchase lineage is attached only when a matching purchase exists; an unmatched refund does not establish a browser or advertising attribution link. Do not assume Stripe copies Session metadata onto refund objects; see Stripe metadata propagation.

Why is the Stripe purchase missing?

Symptom	Check or recovery
Signature rejected with `400`	Check that Plainrouter holds this endpoint’s signing secret. After fixing it, resend through Stripe so the delivery has a fresh signature.
`received: true` but `ignored: true`	Read `reason`; `workspace_inactive` requires activating the workspace. A successful HTTP response alone is not a recorded purchase.
Completed Session, no purchase	Inspect `payment_status` and subscribe to asynchronous success. Do not create a purchase while payment is pending.
Paid Session, duplicate response	Inspect the original returned event ID; do not create another Session or purchase to force a new record.
Revenue exists but no Meta delivery	This adapter does not establish advertising consent or an attributed visitor join. Review your purchase owner before adding another sender.

Stripe webhook redelivery and Plainrouter destination replay are different operations. Destination replay cannot create a missing Stripe revenue record.

Reliability behavior

Event requests use browser keepalive where available.
A granted event still in flight during pagehide is also sent as a text beacon.
Conversion-event requests can receive at most one retry after network failures or retryable responses, within the request’s retry budget. Arrival requests are never retried.
Landing click IDs stay in document memory and are transmitted only with a complete consent grant; the legacy pr_click_ids cookie is no longer used for storage.
First-party browser identifiers can still have shorter lifetimes when a browser applies its own storage restrictions.

Avoid duplicate Meta events

After you connect Meta, continue to track through signalq. The managed browser Pixel and Plainrouter server delivery share one event ID. Choose one purchase owner before adding a confirmation-page event:

Purchase owner	Event ID and retry behavior
Browser `signalq("track", "purchase", payload)`	Signals generates one ID for its managed browser/server pair. Built-in transport retries preserve it; another `track` call generates another ID.
Your backend using the Node.js SDK or REST API	Your application supplies and persists the ID. Reuse the same ID and purchase payload on retries. A separate `signalq` call does not share it.
Stripe verified revenue	Plainrouter derives the canonical purchase from the settled Checkout Session. Do not add a second browser or custom-backend purchase for that session.

Send one managed purchase after payment confirmation

Use this recipe when the browser owns the purchase. Your application must first confirm payment on its server and supply the paid order’s non-personal string ID, decimal total, currency, and item count. A success URL alone is not proof of payment. Run this code after the Signals script loads and your CMP has reported the full grant. The map shares one attempt between repeated callbacks for the same order in the current document:

const purchaseAttempts = new Map();

function trackConfirmedPurchase(paidOrder) {
  if (!purchaseAttempts.has(paidOrder.id)) {
    const attempt = window.signalq("track", "purchase", {
      order_id: paidOrder.id,
      value: paidOrder.total, // Decimal string, such as "49.00".
      currency: paidOrder.currency,
      num_items: paidOrder.itemCount
    });
    purchaseAttempts.set(paidOrder.id, attempt);
  }
  return purchaseAttempts.get(paidOrder.id);
}

// Call from your app's confirmed-payment handler, after consent is ready.
// paidOrder comes from your server's verified order response.
const eventId = await trackConfirmedPurchase(paidOrder);
if (eventId === null) {
  console.warn("Purchase unconfirmed. Check consent and delivery.");
}

This guard lasts only for the current document. A reload, another tab, or a different sender can still create another purchase. If the same order must survive reloads or job retries with a stable ID, use the backend recipe instead. Do not wrap track in an automatic retry loop: an uncertain response can follow an accepted request, and a new call creates a new ID. The managed flow sends the browser Purchase with Pixel eventID and submits the matching server Purchase with event_id. You do not need an additional fbq or backend purchase call. Passing the returned ID to another API request does not enrich the already-accepted event.

Check the purchase pair

Confirm the order was paid and the CMP reported all three grants before tracking.
Inspect the conversion request’s event_id, event_name, and value data. Internal retries should retain the same ID.
Check the event’s destination delivery trace, then compare the browser and server names and IDs in the intended Meta dataset. Meta’s deduplication guide explains the matching fields.
If duplicates remain, inventory confirmation-page handlers, tag-manager tags, theme Pixels, commerce plugins, Stripe webhooks, and backend jobs. Remove overlapping senders after validating the intended flow.

An accepted collector request proves ingestion. It does not establish that Meta received both sides, deduplicated the purchase, or attributed it to an ad. See How do I verify Meta delivery?.

Check a payload before sending it

Use the local checks alongside the relevant troubleshooting guide:

Missing or duplicate Meta events: inspect a synthetic native Meta payload. This checker expects Meta’s data envelope, not a Plainrouter POST /events body.
Event-ID deduplication: compare browser/server event names and IDs.
Browser identifiers: inspect _fbp and _fbc formatting.

These checks run locally in your browser and do not send events to Plainrouter or Meta. A valid payload or matched event ID does not prove delivery or attribution. Use the sandbox for Plainrouter request validation and the destination checks for actual delivery evidence.

Get started

Signals

Actions

Reference

Legacy Launcher

Track purchases, browser consent, and Stripe revenue

Before you begin

Connect Cookiebot callbacks

How landing click IDs are handled

Track an event

Standard event names

Payload fields

Identify a consenting visitor

Read the visitor ID

Verify Stripe Checkout settlement

What do I need before connecting Stripe?

Configure the webhook

Associate a Checkout Session with your order

How do I verify a settled purchase?

Why is the Stripe purchase missing?

Reliability behavior

Avoid duplicate Meta events

Send one managed purchase after payment confirmation

Check the purchase pair

Check a payload before sending it

​Before you begin

​How does the snippet choose a consent source?

​Set consent

​Connect Cookiebot callbacks

​Verify grant, partial consent, and withdrawal

​How landing click IDs are handled

​Track an event

​Standard event names

​Payload fields

​Identify a consenting visitor

​Read the visitor ID

​Verify Stripe Checkout settlement

​What do I need before connecting Stripe?

​Configure the webhook

​Associate a Checkout Session with your order

​How do I verify a settled purchase?

​Why is the Stripe purchase missing?

​Reliability behavior

​Avoid duplicate Meta events

​Send one managed purchase after payment confirmation

​Check the purchase pair

​Check a payload before sending it

Before you begin

How does the snippet choose a consent source?

Set consent

Connect Cookiebot callbacks

Verify grant, partial consent, and withdrawal

How landing click IDs are handled

Track an event

Standard event names

Payload fields

Identify a consenting visitor

Read the visitor ID

Verify Stripe Checkout settlement

What do I need before connecting Stripe?

Configure the webhook

Associate a Checkout Session with your order

How do I verify a settled purchase?

Why is the Stripe purchase missing?

Reliability behavior

Avoid duplicate Meta events

Send one managed purchase after payment confirmation

Check the purchase pair

Check a payload before sending it