Skip to main content

​
Overview

Meta Catalog Sales campaigns dynamically show products from your catalog to users based on their browsing and purchase behavior — for example, retargeting someone who viewed a product but didn’t buy. For these campaigns to work, Meta needs real-time signals about how users interact with your products. By sending ecommerce events (purchases, add to cart, content views) through Linkrunner, you feed Meta the data it needs to match users to the right products and optimize your ad spend. Linkrunner seamlessly syncs these events with your connected Meta dataset.
Before you begin, make sure you have:
  • A product catalog set up in Meta Commerce Manager
  • Meta Ads integration configured in Linkrunner (see Meta Ads setup)
  • Events integrated in your app via the Linkrunner SDK or API

​
Step 1: Select Catalogue Products

To begin, you need to select your catalogue products within the Meta Commerce Manager. Ensure your product feed is active and products are properly categorized. Select your catalogue products Each product in your catalog has a Content ID and an Item group ID. These are the values you’ll use in the content_ids or item_group_ids fields when sending events — they’re how Meta matches your events back to the correct catalog products. Content ID and Item group ID fields in Commerce Manager

​
Step 2: Verify Dataset ID Connection

Once your catalogue is set up, navigate to the events section. Check if the Dataset ID connected with Linkrunner is present and active. If the Dataset ID is not linked:
  1. Press on Manage Connections.
  2. Find the Dataset ID that is linked with Linkrunner.
  3. Turn the connection ON.
Make sure the linking part is successfully completed before proceeding. Manage connections and turn on Dataset ID

​
Step 3: Required Events

View the dataset ID and check the events list. There are 3 essential events we actually need to send: Note: Any event you want to send for these actions should be mapped with their respective standard commerce manager events in the Linkrunner Dashboard. For example, map your custom add to cart event (e.g., add_to_cart) with AddToCart, your view event (e.g., item_viewed or view_content) with ViewContent, and your payment event (e.g., FIRST_PAYMENT or DEFAULT) with Purchase. Make sure you have integrated the appropriate APIs in your application to send these events. View Dataset ID Events The Catalogue match rate shown in Commerce Manager measures the percentage of product IDs in your events that successfully match products in your catalog. Meta recommends maintaining a match rate of 90% or higher for optimal ad targeting and delivery. If your match rate is low, double-check that the content_ids or item_group_ids in your events exactly match the IDs in your catalog.

​
Understanding event_data

When sending events via the Capture Event API or Capture Payment API, you must include specific fields in your event_data payload for Meta to correctly attribute and optimize your catalogue sales.

​
Required Fields for Ecommerce Events

ParameterTypeDescription
content_ids / item_group_idsarrayRequired for Purchase, AddToCart, ViewContent.
content_ids: Use an array of single product IDs for variants. Example: ['id1', 'id2'].
item_group_ids: Use for full product groups to boost the entire group.
contentsarray of objectsRequired for Purchase, AddToCart, ViewContent.
Array detailing items included:
id: Matches content_ids / item_group_ids.
quantity: Number of items.
item_price: Unit price (must match Meta Products catalog).
content_typestringRequired for Purchase, AddToCart, ViewContent.
Set to "product" for content_ids, or "product_group" for item_group_ids.
valuenumberRequired for Purchase, AddToCart.
Total numeric value (e.g., item_price * quantity). No currency symbols.
currencystringRequired when value is sent.
The 3-letter ISO currency code (e.g., "USD", "INR").
num_itemsnumberRequired for Purchase, AddToCart.
Total quantity of items in the contents array.
order_idstringRequired for Purchase.
Backend-generated unique purchase order ID.
The item_price in the contents array should match the product price in your Meta catalog. Mismatched prices can lower your catalogue match rate and affect ad optimization.
Example event_data Payload: 
"event_data": {
    "content_ids": [
        "whshct4mwc"
    ],
    "contents": [
        {
            "id": "whshct4mwc",
            "quantity": 2,
            "item_price": 1000
        }
    ],
    "content_type": "product",
    "currency": "INR",
    "value": 2000.00,
    "num_items": 2,
    "order_id": "order_id_1234"
}
Note: For full integration details and request examples, refer to the Capture Event API and Capture Payment API documentation.

​
Testing Ecommerce Events

After you have integrated the APIs and started sending events, you will naturally want to verify everything is working correctly.
  1. Send a Test Event: Trigger an event using the Capture Event API (e.g., add_to_cart) or the Capture Payment API (e.g., Purchase).
  2. Check the Meta Events Manager: Navigate to your Commerce Manager > Events section.
  3. Wait for Status Updates: Within 15 minutes of sending your event, you should start seeing the status reflect that you are successfully hitting the Meta Commerce dataset.
Commerce Manager Events Testing Verification Note: While the real-time hits will show up in Events Manager within 15 minutes, please be aware that it can take a few days for the actual data to fully reflect and populate across all Commerce Manager dashboards.

​
Creating a Catalog Sales Campaign

Once your events are flowing and your catalogue match rate is healthy, you can create a Catalog Sales campaign in Meta Ads Manager:
  1. Go to Meta Ads Manager → Create Campaign → select the Sales objective and choose your catalog.
  2. Select the catalog that is connected to your Linkrunner dataset.
  3. Under ad set, choose your targeting strategy:
    • Broad audience — Meta finds new customers likely to purchase from your catalog.
    • Retargeting — target users who have already interacted with your products (e.g., viewed content or added to cart but didn’t purchase).
  4. Configure your budget, placements, and creative, then publish.
Retargeting audiences are automatically built from the ViewContent, AddToCart, and Purchase events you send through Linkrunner. The more event data Meta receives, the better it can optimize delivery.