hermosodocs

Meta Conversions API: send sales and leads to your pixel

The Meta pixel in a browser misses sales: ad blockers, closed tabs, a phone order, a deal closed in your CRM. The Conversions API sends those events to the same pixel from the server, so Meta can count them and your ads can learn from them. Hermoso sends to the pixel on your own connected ad account. It costs no credits.

Before you start

Sending events

send_meta_conversions takes up to 1,000 events per call. Each event has:

A website event also needs eventSourceUrl (the page) and clientUserAgent, because Meta requires both for website events.

Hashing

Pass plain values. Hermoso normalizes each one the way Meta's Customer Information Parameters page says (lowercase email, digits-only phone with its country code, a two-letter state code, the first five digits of a US zip, and so on) and SHA-256 hashes it before it leaves the server. Never hash values yourself: a digest made the wrong way is accepted by Meta and matches nobody. A value that is already a SHA-256 digest is passed through and never hashed twice. The IP address, user agent, fbc, fbp and lead id are sent as they are, because Meta says not to hash them. externalId is hashed by default; pass hashExternalId: false if your browser pixel sends it unhashed, so the two match.

What the reply tells you

The reply is Meta's own answer: eventsReceived, any messages, and the fbtraceId to quote to Meta support. Received is not matched: Meta matches each event on its side, and only matched events count toward your ads. Events show in Events Manager within about 20 minutes. If Meta refuses a batch, its sentence comes back as written. Meta may still keep the valid events from a refused batch, so when every event has an eventId, fixing the problem and sending the same batch again is safe.

Testing

Copy the code from Events Manager, Test Events, and pass it as testEventCode. The events appear in the Test Events window. Meta does not throw test events away: they still flow into Events Manager and are used for targeting and measurement, so test with real events or on a pixel that runs no live ads.

Limited Data Use

Limited Data Use tells Meta to process an event as a service provider under its state-specific terms, for US state privacy laws. Set limitedDataUse per call or for the brand: off, on (Meta works out the person's state), or the code of a state it applies in (ca, co, ct, fl, or, tx, mt, de, ne, nh, nj, mn, md, ri). Meta notes that campaign performance, retargeting and measurement may be limited when it is on.

Pixel health

meta_dataset_quality reads Meta's Dataset Quality API for the pixel: the event match quality score out of 10 for each website event, which match keys arrive and how often, Meta's list of problems with the fix for each, how much of your browser traffic the server also covers, deduplication coverage, and how fresh and how late the uploads are. Meta scores website events only.

Automatic sending

set_meta_conversions_auto (or the Conversions API button on the Meta card in Connectors) turns on sources that send by themselves, every hour by default. Each source is off until you turn it on, and turning one on needs your confirmation and your consent statement.

SourceWhat is sent
Shopify ordersEach paid order as a Purchase, with the order id as the event id, the order total, and the buyer's hashed email. Test and cancelled orders are skipped. Point-of-sale orders are sent as physical_store; web orders are sent as other, because Shopify gives an app no browser user agent and Meta requires one for a website event. If your store already sends purchases through Meta's own Shopify app, leave this off. This source waits on Shopify approving Hermoso to read order and buyer details.
Meta lead form leadsEach new instant form lead, sent back as Lead with its lead id, the way Meta's Conversion Leads integration describes.
Email leads who replyAn email lead becomes a Lead when they reply to your outreach. A lead you imported but who has not replied is not a conversion and is not sent.

A source sends what happens after you turn it on, never your history. An event is never sent twice. A send that fails is kept and tried again on the next run (within 15 minutes); one that grows too old for Meta to take is listed as expired in the reply, never dropped without a word. Turning a source off stops it straight away, including anything waiting to be retried.

API routes

POST /api/meta/conversions, GET /api/meta/dataset-quality, GET /api/meta/conversions/auto and POST /api/meta/conversions/auto. In MCP, the three tools are in the ads group: they are listed once Meta is connected and ads tools are on, and reachable any time through find_tools and call_tool.

Example

send_meta_conversions {"adAccountId": "act_1234567890", "pixelId": "1528885075058847", "events": [
  {"eventName": "Purchase", "actionSource": "phone_call", "eventId": "order-1042",
   "email": "jane@example.com", "phone": "+1 650 555 1212", "value": 129.99, "currency": "USD"}]}
  → "Meta received all 1 event(s) on pixel "Pixel-1" (1528885075058847). Received is not matched: ..."