Tracking and attribution

Meta Conversions API (CAPI): a complete guide for ecommerce stores

The Conversions API sends your store's sales from the server straight to Meta. Here are the ecommerce events, required fields, hashing rules and how deduplication with the pixel works.

Laptop in front of a server rack showing a dashboard of confirmed conversion events

The Meta Conversions API (CAPI) lets your store send events such as purchases, add to cart and checkout straight from its server to Meta, without relying on the shopper's browser. It works alongside the Meta Pixel: both send the same event with the same ID, Meta counts it once, and you recover the sales the pixel would have missed.

This guide is for store owners running Facebook and Instagram ads who want Ads Manager to receive every paid purchase. It's part of our hub on tracking and attribution. If server-side sending is new to you, start with our guide to server-side tracking, then come back for the Meta specifics.

What is the Meta Conversions API?

The Conversions API is Meta's interface for events sent by a server. The official documentation describes it as a connection between an advertiser's marketing data and Meta's optimization and measurement systems, and says server events are processed like events sent with the Meta Pixel.

In practice, your store knows when an order is paid, because Stripe, PayPal or whichever processor you use tells the server. With the API, the store passes that fact on to Meta right away: "the $49 order, with these items, was paid by this person". The pixel in the browser is still there, but it's no longer the only source of truth.

If I already have the pixel, why use the Conversions API?

Because the pixel loses events you never see. Ad blockers stop the script from loading. Safari limits the lifetime of cookies set by scripts. Some payments, such as bank transfers or local methods like Brazil's Pix, confirm after the shopper has left the page. Every lost event is a sale the algorithm can't learn from.

In its Conversions API best practices, Meta recommends using the API in addition to the pixel and sharing the same events through both, because the API lets you share website events the pixel may lose. The same page asks you to send events as they happen, in real time or in batches close to real time.

Which events should an online store send?

The standard ecommerce events cover the whole journey. A solid starting point:

EventWhen it firesData that matters
PageViewAny page openedPage URL
ViewContentProduct pageProduct ID, value and currency
AddToCartProduct added to cartID, quantity, value and currency
InitiateCheckoutCheckout startedItems, cart value and currency
PurchasePayment confirmedAmount paid, currency, items and customer data

Purchase carries the most weight. It has to fire on confirmed payment, not when the order is created. An unpaid order isn't a purchase. If your checkout reports every created order as Purchase, Meta optimizes for people who start paying, not for people who pay.

Which fields does each event need?

Meta lists the event fields in its server event parameters. The ones that show up most in setup errors:

  • event_name: the event name, identical to the pixel's (Purchase, AddToCart…).
  • event_time: when the event happened. Meta accepts events up to 7 days before you send them; anything older makes the whole request fail.
  • action_source: where the conversion happened. For an online store, website.
  • event_source_url: the URL of the page where the event happened.
  • event_id: the ID that lets Meta deduplicate against the pixel. The API accepts events without it, but then the purchase counts twice.
  • user_data: customer data, covered in the next section.
  • custom_data: value, currency and contents on commerce events.

What customer data should you send, and what needs hashing?

For Meta to tie a purchase to the person who saw the ad, the event carries customer data. The rules are in the customer information parameters:

FieldWhat it isHash it?
emEmail, trimmed and lowercasedYes, SHA-256
phPhone, digits only, with the country code (1 for the US)Yes, SHA-256
external_idCustomer or visitor ID in your storeRecommended
fbpBrowser cookie set by the pixelNo
fbcAd click identifierNo
client_ip_addressShopper's IP addressNever
client_user_agentShopper's browserNo

A common mistake is sending phone numbers without the country code; Meta needs it to use the number for matching. Another is hashing fbp and fbc, which must be sent as they are.

How does deduplication with the pixel work?

With the pixel and the API sending the same event, Meta has to know it's a single purchase. The rule is on the page about deduplicating pixel and server events:

  • the pixel's eventID must equal the API's event_id;
  • the event name must be the same on both (Purchase and Purchase);
  • deduplication applies to events received within 48 hours of the first one with that ID;
  • when the two don't differ in a meaningful way, Meta generally keeps the one received first.

The safe way to get the same ID on both sides is to derive it from the order rather than generating a random number in the browser. That way the server reaches the same value without depending on what happened on the page.

What is Event Match Quality?

It's a score Meta shows in Events Manager to tell you how well the customer data in your events helps find the right person (see Event Match Quality). According to Meta's best practices, it's only available for web events. What helps most:

  • collecting email and phone at checkout and sending both on Purchase;
  • passing the browser's fbp and fbc into the server event;
  • sending external_id consistently across every event from the same visitor;
  • using the shopper's IP and user agent, not your server's.

How to set up the Conversions API on your store

There are three routes: your own tagging server (such as GTM server-side), a third-party tracking tool, or native sending from your store platform. The comparison is in our server-side tracking guide. In Horsee, sending is native, and the steps are:

  1. In Meta Events Manager, open your pixel and copy the pixel ID.
  2. In the pixel's settings, under the Conversions API section, generate an access token.
  3. In Horsee, open Tracking in the sidebar and add Meta (pixel and Conversions API).
  4. Paste the pixel ID and the token. To watch events live, also paste the test event code from Events Manager.
  5. Keep both browser and server sending on. The same event through both channels counts once.
  6. Save and send a test event. Check it in Meta's test events tool.

From then on, the store sends PageView, ViewContent, AddToCart, InitiateCheckout and Purchase with no extra setup. The server-side purchase fires when the order is marked as paid, with any connected processor, and a background job resends paid purchases that never reached Meta. The token is stored encrypted. Screen-by-screen help is in the Horsee Help Center, and everything that comes with it (automation, CRM and a data copilot) is on the Horsee operations page.

How do you test before trusting the numbers?

  1. With the test event code active, browse your store and watch each event appear in the test events tool.
  2. Place a real, low-value order and close the tab as soon as you've paid. The purchase must still arrive.
  3. Open the Purchase event and compare value, currency and items with the order.
  4. Check that the event shows as received from both the browser and the server, and counted once.
  5. After a few days, review Event Match Quality and any diagnostics warnings in Events Manager.
  6. Remove the test event code when you're done so events count normally again.

What are the most common Conversions API mistakes?

  • Two senders with different IDs. An old tracking app and native sending at the same time. Meta gets two purchases and ROAS looks better than it is.
  • An expired or revoked token. The server tries and Meta rejects it, but the pixel keeps sending, so nobody notices. Check the server-side failure rate every week.
  • Purchase with no value or the wrong currency. A store priced in USD sending EUR, or a zero-value Purchase. Value optimization goes blind.
  • Events sent too late. Replaying purchases from weeks ago gets the request rejected, because the limit is 7 days.
  • Ignoring consent. If your store requires consent for marketing cookies, server events must respect the same choice. In Horsee, the Show consent banner setting makes pixels fire only after the visitor accepts. It's off by default, and turning it on is your call, based on the rules that apply to you, such as the GDPR in the EU, and your legal advice.

Does the Conversions API improve ROAS?

It improves measurement, and better measurement usually improves optimization. With more purchases coming in, the algorithm learns from more examples of real buyers. But the API doesn't change Meta's attribution rules: sales are still credited by window and click date. To see how much each campaign sold in paid orders, cross-check with UTMs in your own store data. And once tracking is reliable, look at the other end of the funnel: the sales you lose at the cart, covered in our guide to abandoned cart recovery.

Frequently asked questions

What is event_id in the Conversions API?

It's the event's unique identifier. When the pixel and the server send the same event with the same event_id and name, Meta counts it once.

Can I use the Conversions API without the pixel?

You can, but Meta recommends using both and deduplicating. The pixel adds cookies and the click identifier that help match the event to a person.

How do I know deduplication is working?

In Events Manager, the event shows as received from both the browser and the server. If purchases are roughly double your paid orders, the IDs don't match.

Do I need a developer to set up the Conversions API?

For a self-hosted tagging server, yes. On store platforms with native sending, you paste the pixel ID and access token into your store dashboard.

How long after a purchase can I send the event?

Meta accepts events up to 7 days old but recommends sending them as they happen. Anything older gets the request rejected.

Keep reading