Skip to content

Meta Lead Ads

Menu Location: Customers > Reports > Meta Lead Ads (also listed under Kiva Tools as Facebook Leads / Instagram Leads / Instant Forms)

Overview

Meta Lead Ads connects your store to Facebook and Instagram "Instant Form" lead ads. When someone submits one of your Instant Forms, Meta sends the lead here automatically with their name, email, phone, and zip pulled from their Facebook/Instagram profile, no typing required on their end. The store checks whether their zip is in your delivery area, then emails them a link to finish signing up that is already prefilled with their details, so all they have to do is pick a box and add payment. Leads outside your delivery area are still saved and get a short "not in your area yet" note instead. Each lead is fetched once and deduplicated, so the same person is never processed twice.

This feature is off by default and must be enabled per store.

Primary Features

  • Enable / Disable toggle for the whole integration
  • Setup panel showing the webhook/callback URL to paste into your Meta app, and the configured/missing status of the three required secrets (app secret, verify token, page access token, all set in your store's environment file, not in this admin page)
  • Two admin-editable follow-up email templates: "Meta Lead Signup" (sent when the lead's zip is in your delivery area, contains the prefilled finish-signup link) and "Meta Lead Waitlist" (sent when the zip is out of area, no signup link)
  • Field mapping (optional): most Instant Forms are auto-detected; if a field (email, phone, zip, first/last/full name, city, state) keeps coming through blank because your form used an unusual question name, you can map it here as JSON
  • Recent leads table: the last 100 leads with Received date, Name, Email, Phone, Zip, In area (Yes/No), Emailed date, and Status (received, emailed, out of area, no email, error, or signed up)

Common Use Cases

Use Case 1: Turn On Meta Lead Ads

Goal: Start capturing leads from an existing Facebook/Instagram Instant Form

Steps:

  1. Open Customers > Reports > Meta Lead Ads
  2. Copy the webhook/callback URL shown under Setup
  3. In your Meta app, set that URL as the leadgen webhook and add your app's App Secret, Verify Token, and Page Access Token to your store's environment file
  4. Once all three show "configured", click Enable

Use Case 2: Fix a Field Coming Through Blank

Goal: A form question (e.g. zip) is not being captured

Steps:

  1. Check the Recent leads table to confirm which field is blank
  2. Note the exact question name used on your Instant Form
  3. Under Field mapping, enter JSON such as {"zip":"postal_code"} mapping our field name to your form's exact question name
  4. Click Save mapping; the mapping only affects leads fetched after saving

Use Case 3: Edit the Follow-Up Emails

Goal: Change the wording sent to captured leads

Steps:

  1. Click Meta Lead Signup or Meta Lead Waitlist in the follow-up emails table
  2. Edit the template in the normal email editor
  3. Available placeholders: **company**, **lead_first_name**, and (Signup email only) **signup_link** and **signup_link_full**

Troubleshooting

Secrets show "missing"

The app secret, verify token, and page access token are read from your store's environment file (META_APP_SECRET, META_VERIFY_TOKEN, META_PAGE_TOKEN), not entered on this page. Until all three are present, live leads cannot be fetched, though you can still complete Meta's webhook handshake and test with Meta's Lead Ads Testing Tool.

A lead shows status "no email"

The Instant Form submission did not include a usable email address, so no finish-signup link could be sent. Check the field mapping if your form asks for email under an unusual question name.

A lead shows status "error"

The Graph API fetch for that lead's details failed (for example an expired page access token). Check the store's error logs for the specific Graph API error.

Their submitted zip code did not match your delivery area, so they received the waitlist email instead of a signup link.

  • Missed Signups - people who started the normal signup form but did not finish
  • Missed Zip Codes - people who tried to sign up but their zip is not in your delivery area
  • New Signups - the latest customers who completed signup

Recent Updates

August 12, 2026: New feature. Meta Lead Ads (Facebook/Instagram Instant Forms) integration added: webhook lead capture with dedup, per-tenant admin page (Customers > Reports > Meta Lead Ads), admin-editable follow-up emails, zip-based delivery-area routing, and automatic conversion tracking when a lead completes signup.