Usage

Browser and server events

Every event is created on the server with one event_id. That ID is used twice:

• Browser: the storefront script calls fbq('trackSingle', '<pixel>', '<Event>', {...}, {eventID: '<event_id>'}).
• Server: the same event, with the same event_name and event_id, goes into the Conversions API queue. It also carries event_time, action_source: website, event_source_url, user_data and the same custom_data.

Meta keeps the first copy it receives and drops the second. If the browser is blocked (ad blocker, iOS tracking prevention, closed tab), the server copy still counts.

Purchases use a stable ID derived from the order, order.<order_id>.<signature>. The browser Purchase is printed on the confirmation page only once, and the server Purchase is queued once, when the order reaches one of the purchase statuses. Reloading the thank-you page, or a payment that is confirmed hours later, never creates a second purchase.

custom_data follows Meta’s standard parameters: content_ids, content_type: product, contents (id, quantity, item_price), value, currency, content_name and content_category on single products, num_items, search_string for Search, and order_id for Purchase.

Advanced matching and hashing

Customer fields are normalised by Meta’s rules and hashed with SHA-256 on your server:

Field	Normalisation	Example
em	trim, lowercase	[email protected] → [email protected]
ph	digits only, no leading zeros, with the country calling code of the customer’s country	0532 123 45 67 (TR) → 905321234567; (650) 555-1212 (US) → 16505551212
fn, ln	lowercase, no punctuation, UTF-8	Mary-Ann → maryann, Valéry → valéry
ct	lowercase, letters only, no spaces	New York → newyork
st	US: 2-letter code; elsewhere the state name, lowercase, no spaces or punctuation	CA → ca
zp	lowercase, no spaces or dashes; US: first 5 digits	94035-1234 → 94035, M1 1AE → m11ae
country	ISO 3166-1 alpha-2, lowercase	US → us
db	YYYYMMDD	1997-02-16 → 19970216
external_id	cscart_<user_id>, hashed

client_ip_address, client_user_agent, fbp and fbc are never hashed. The browser pixel receives the same hashed values in fbq('init', …), so the page source never contains plain email addresses or phone numbers.

Consent

When consent handling is active (see Configuration):

1. Before a decision: the pixel library is not loaded and no cookie is written. Browser events of the page wait in memory, and their server copies wait in the visitor’s session for up to 30 minutes. Nothing is sent.
2. Consent granted (cookie dialog, Kavio Labs consent banner or kvMetaCapi.consent(true)): the script tells the server, which writes _fbp/_fbc and queues the waiting server events. Then the pixel loads and sends the waiting browser events with the same IDs. Orders placed in this session before consent get their server Purchase too.
3. Consent denied: waiting events are dropped on both sides. If the pixel was already running, it is switched off with fbq('consent', 'revoke').
4. Later pages know the decision: from the consent add-on’s own cookie when the Kavio Labs consent add-on is active, otherwise from the kv_meta_consent cookie (g or d) that the add-on writes.

With the Kavio Labs cookie consent add-on, that add-on is the single source of truth. When its policy version changes, visitors have no valid decision again and the pixel waits, even if kv_meta_consent still says g.

The queue and the event log

Open Marketing → Meta events log.

Status	Meaning
Queued	Waiting to be sent
Sending	Taken by a worker (released after 5 minutes if the worker stops)
Retry scheduled	Meta or the network had a temporary problem; retried after 1, 5, 15, 60 and 180 minutes
Sent	Accepted by Meta (events_received)
Failed	Permanent error (for example an invalid token) or 6 attempts used. The error message is in the row.
Expired	Older than Meta accepts (7 days)

Click Payload to see the exact JSON sent to Meta and Meta’s response. The tools menu has Send queued events now, Retry failed events (after you fixed the token, for example) and Clear the log. If Meta rejects a batch because of one invalid event, the add-on resends the events one by one, so one bad event does not block the others.

Catalog feed

Copy the CSV or XML URL from the Catalog feed tab into Commerce Manager as a scheduled feed. Columns: id, title, description, availability, condition, price, sale_price, link, image_link, additional_image_link (up to 10), brand, item_group_id (variation group, vg<group_id>), product_type (category path) and mpn (product code).

• id is the same content ID the pixel sends, so catalog ads can match views, carts and purchases to items.
• price is the regular price (list price or price before catalog promotions) and sale_price the current price when it is lower.
• Product variations are listed one by one and grouped with item_group_id.
• Only active products visible on the storefront are listed. The feed is streamed page by page, so large catalogs do not need more memory.
• On Multi-Vendor, vendors with the pixel feature see their own feed URL (&vendor_id=<id> with a vendor key) in their profile.

Vendor pixels

On Multi-Vendor, turn on Allow vendors to add their own pixel. Each vendor then gets a Meta Pixel block on the Add-ons tab of their profile, in the vendor panel and in the admin panel:

• Pixel ID: required to enable the vendor pixel.
• Conversions API access token: optional, for server events to the vendor’s pixel. The field stays empty after saving. Leave it empty to keep the saved token, or enter - to remove it.
• Test event code: optional.

The Save pixel settings button saves only this block, so the rest of the vendor profile is not sent to premoderation. A vendor pixel receives PageView and ViewContent on the vendor’s product and store pages, AddToCart and AddToWishlist for the vendor’s products, InitiateCheckout and AddPaymentInfo for carts that contain them, and one Purchase per vendor order. Vendor pixels get the browser identifiers (fbp, fbc, IP address, user agent) but no hashed customer data. The marketplace pixel gets one Purchase per checkout, with the full checkout value.

Debugging

• Turn on Debug mode and open the browser console: every call is logged as [Meta CAPI] <Event> <pixel> <event_id> {...}.
• kvMetaCapi.sent in the console lists the events sent on the current page.
• Use Test event code together with Events Manager → Test events, and check the event log for the server side.