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
- Connect Meta under Connectors and tick the ad account that owns the pixel. The pixel must be on that ad account: Hermoso checks every pixel id against the account's own pixel list and refuses any other.
- The person who connected Meta needs access to the pixel in their Meta business. If they do not have it, Meta's own message comes back.
- Consent is yours. Meta's Business Tools Terms require that your customers were told, and agreed where the law requires it, that their details may be shared with Meta. Hermoso hashes the details and sends only what you ask it to, but the notice and consent are your responsibility.
Sending events
send_meta_conversions takes up to 1,000 events per call. Each event has:
eventName: Purchase, Lead, CompleteRegistration, AddToCart, InitiateCheckout, ViewContent, Contact, Subscribe, any other Meta standard event, or a custom name of up to 50 characters. A standard name in the wrong case is sent with Meta's spelling, and the reply says so.actionSource: where it happened. One of website, email, app, phone_call, chat, physical_store, system_generated, business_messaging or other. Meta asks you to state this accurately.eventTime: when it happened, as a unix time in seconds or an ISO date. Meta takes events up to 7 days old (62 days for physical_store) and refuses the whole request otherwise, so Hermoso refuses first.eventId: a unique id, such as the order number. Send the same id your browser pixel sends aseventID, and Meta counts the purchase once, not twice.- At least one way to match the person:
email,phone(with the country code),firstName,lastName,dateOfBirth,gender,city,state,zip,country,externalId,clientIpAddresswithclientUserAgent,fbc(or the rawfbclidfrom the landing page address),fbp, or a MetaleadId. valueandcurrency(required on Purchase), and optionallyorderId,contentIds,contentsandnumItems.
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.
| Source | What is sent |
|---|---|
| Shopify orders | Each 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 leads | Each new instant form lead, sent back as Lead with its lead id, the way Meta's Conversion Leads integration describes. |
| Email leads who reply | An 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: ..."