Skip to main content

Meta Ads Integration Guide

Connect Meta Ads to export AI-predicted customer audiences as Custom Audiences. This enables precise targeting of high-intent buyers for improved campaign performance.

Prerequisites​

Before starting, ensure you have:

  1. Meta Business Manager account - Create at business.facebook.com
  2. Business ad account - Required for Custom Audiences from customer lists
  3. Trained Flexsee model - At least one e-commerce prediction model
  4. Meta Pixel (for Publish advert only) - A Pixel connected to your ad account. Required when you use Publish advert to create the full ad campaign; not needed for Custom Audiences only.
Business Account Required

Custom Audiences from customer lists (what Flexsee creates) require a Business Manager ad account. Personal ad accounts will fail with permissions errors.

1. Flexsee Meta App and development mode​

The Meta Ads integration uses Flexsee's Meta App. You do not need to create or configure a Meta App yourself.

  • Production: Once Flexsee's app is approved by Meta, you can connect directly from Integrations → Meta Ads.
  • Development mode: If Flexsee's integration is still in Development, your Facebook account must be added as a Tester on the Flexsee Meta App. If Connect Meta Ads fails or you don't see the option, contact support@flexsee.ai to be added. Publish advert does not work in Development; use Generate campaign with audience and create the ad in Meta Ads Manager.
Beneficiary (EU, UK, Australia)

For ads targeting the EU, UK, Australia and similar regions, Meta requires a Beneficiary (the person or organisation benefitting from the ads). Flexsee uses your ad account’s Business name by default. If you see "Enter the person or organisation benefitting from the ads", in Meta go to Ad account → Advertising settings → Verifications & ad transparency → Beneficiary and payer, or ensure your ad account is owned by a Business.

2. Create Business Ad Account​

Custom Audiences from customer data require a Business Manager ad account:

Create Business Manager​

  1. Go to business.facebook.com
  2. Click "Create Account"
  3. Enter business details
  4. Complete business verification if required

Create Business Ad Account​

  1. In Business Manager: Business Settings → Ad Accounts
  2. Click "Add" → "Create a new ad account"
  3. Configure:
    • Name: Your Company Ads
    • Time zone: Your business timezone
    • Currency: USD (or preferred)
  4. Click "Create Ad Account"
  5. Assign yourself as Admin

Verify Ad Account Type​

Confirm your ad account is managed by your Business:

  1. Go to Business Settings → Ad Accounts
  2. You should see your ad account listed
  3. "Owned by" should show your Business name
Personal vs Business Accounts

If "Owned by" shows your personal name instead of your Business, the account is personal and won't work for Custom Audiences.

Development mode

In Development mode, only people with Tester (or Admin) role on the Flexsee Meta App can connect. Contact support@flexsee.ai to be added.

3. Connect Meta Ads to Flexsee​

Initiate Connection​

  1. Log in to Flexsee dashboard
  2. Navigate to Integrations → Meta Ads
  3. Click "Connect Meta Ads"

OAuth Authorization Flow​

  1. You'll be redirected to Meta's authorization page
  2. Review requested permissions:
    • ads_management - Create and manage audiences
    • ads_read - Read ad account information
    • business_management - Access Business Manager
  3. Click "Continue" to authorize
  4. You'll be redirected back to Flexsee

Verify Connection​

After successful OAuth, you should see:

✅ Meta Ads Connected
Ad Account: act_XXXXXXXXXXXXX (Business account)

The system automatically selects your Business ad account if you have multiple accounts.

4. Meta Pixel (for Publish advert)​

If you use Publish advert to create the full ad campaign (campaign + ad set + creative + ad) in one click, you need a Meta Pixel connected to your ad account.

When it's required​

  • Publish advert (after the audience is created) — creates a conversion campaign optimized for purchases. Meta requires a Pixel so it knows which conversion source to use for optimization and attribution.
  • Generate campaign with audience (Custom Audience only) — does not require a Pixel.

Why a Pixel?​

Flexsee creates campaigns with OFFSITE_CONVERSIONS optimized for PURCHASE. Meta needs a conversion source (your Pixel) to receive purchase events from your site and to optimize delivery. Without a Pixel, the API returns "Select a promoted object for your ad set" and campaign creation fails.

How to set up​

  1. Create or choose a Pixel (dataset)

    • Business Settings (business.facebook.com/settings) → Data sources → Datasets and pixels → + Add to create a new dataset (Pixel) or add an existing one to your Business.
    • Or Events Manager (business.facebook.com/events_manager) / Meta Business Suite → Datasets: view and manage datasets. Click a dataset to open Overview, Test events, Diagnostics, History, Settings. Note the Pixel ID (in the list or in Settings).
    • "Dataset is not receiving events" or "Your dataset hasn't received any activity" is normal until you complete the steps below.

  2. Connect the Pixel to your ad account
    The Pixel must be linked to the same ad account you use in Flexsee (the one you connected via OAuth), or Publish advert will fail with "No Meta Pixel found for this ad account".

    • Business Settings (business.facebook.com/settings) → Data sources → Datasets and pixels.
    • In the list on the left, click your dataset (e.g. "Flexsee AI Pixel Dataset"). In the right-hand pane, open the Connected assets tab (next to People and Partners).
    • Click Connect assets → choose Ad account → select the ad account you use in Flexsee (e.g. "Flexsee AI Ads") → confirm. Once linked, the ad account appears under Connected assets; you can Disconnect there if you need to change it later.
    • "Dataset is not receiving events" can still show after this—that refers to event traffic from your site or app (step 3). Linking the ad account here is what fixes "No Meta Pixel found for this ad account" so Publish advert can run.
    • If Connected assets is not available, try Accounts → Ad accounts → [your ad account] → Assign / Data sources → add the Pixel.

  3. Send Purchase (and ideally ViewContent, AddToCart) to your Pixel
    In Events Manager or Datasets → select the pixel → Overview shows:

    • Gather website events from browser activity → Set up Meta Pixel (code snippet on your site), or
    • Send events from a server → Set up Conversions API.
    • If you use the Flexsee AI Predictions Shopify app: In Shopify admin, go to Settings → Customer events and open the Flexsee AI Tracking Pixel. Set Meta Pixel ID (optional) to your Pixel ID. The pixel will forward ViewContent, AddToCart, and Purchase to your Meta Pixel—no extra code. See Shopify — Flexsee AI Predictions app and tracking pixel.
    • Otherwise: Use Set up Meta Pixel or Set up Conversions API so Purchase (and ViewContent, AddToCart if possible) are sent when customers browse and buy.
Future: choosing the campaign objective

We may support selecting the campaign objective in the flow (e.g. link clicks vs conversions). Objectives like LINK_CLICKS do not require a Pixel. That is not in the current MVP.

5. Accept Custom Audience Terms​

First-time Custom Audience creation requires accepting Meta's terms:

  1. When you first create an audience, you may get an error about terms
  2. Click the link in the error message, or visit: 
    https://business.facebook.com/ads/manage/customaudiences/tos/?act=YOUR_AD_ACCOUNT_ID
  3. Review and accept the Custom Audience Terms of Service
  4. Return to Flexsee and retry creating the audience

6. Create audiences and campaigns​

Use Wizard Flow as the primary path. Campaign creation from Models has been replaced by the wizard.

Launch from Wizard Flow​

  1. Go to Wizard Flow → Create flow (or start from Products → Launch wizard on a catalog item).
  2. Complete Data source, Sync, and Readiness.
  3. Choose Meta Ads as the destination.
  4. On Targeting, select a product and predictive audience segment.
  5. On Destination setup:
    • Retargeting — uploads a Custom Audience of predicted buyers for that product.
    • Prospecting — uploads a seed audience, then creates a lookalike (seed must have at least 100 users). Choose lookalike size (1%, 2%, or 5%) and country (GB, US, CA, AU).
    • Set campaign name, budget, headline, description, and destination URL.
    • Checkout route: Store product page or Flexsee Quick Pay (Stripe Connect).
  6. On Activate, launch the flow. Flexsee creates the Custom Audience in Meta (and lookalike when prospecting).
  7. From the flow detail page or activation success state, optionally click Publish advert to create the full ad campaign (campaign + ad set + creative + ad) in one click. Publish advert requires a Meta Pixel — see Meta Pixel (for Publish advert).

Review performance on Campaigns — Campaigns & attribution.

View in Meta Ads Manager​

  1. After creation, go to Integrations → Meta Ads
  2. Find your audience in the list
  3. Click "View in Meta" to open Meta Ads Manager
  4. Create ad campaigns using this audience

Download audience as CSV​

Flexsee saves a snapshot of each audience when it is created. You can download the audience as CSV:

  1. Go to Integrations → Meta Ads
  2. Find your audience in the list
  3. Click Download to export the audience (user_id, email, firstName, lastName, phone, score) as CSV

Useful for auditing, backup, or importing into other tools. Only audiences created after this feature are downloadable.

7. How It Works​

Data Flow​

Privacy & Security​

  • Email Hashing: All emails are hashed using SHA-256 before transmission
  • PII Protection: Names and phones (if available) are also hashed
  • Secure Storage: Meta access tokens are encrypted at rest and validated server-side before use
  • GDPR Compliance: Data deleted upon account closure

Operational Notes​

  • Connection status includes the last token validation time, any known token expiry, and the latest Meta usage-header snapshot returned by the Ads API.
  • Customer-file audience uploads are batched automatically for larger lists, and the upload flow supports usersreplace plus Meta data-processing options when required.

Audience Types​

Custom Audiences (Retargeting):

  • Target existing customers predicted to buy a specific product
  • Great for product launches and inventory clearance

Lookalike Audiences (Prospecting):

  • Find new customers similar to a high-intent seed audience for a product
  • Created in Wizard Flow when objective is Prospecting (minimum 100 users in the seed)
  • Flexsee uploads the seed, asks Meta to build the lookalike, and targets the campaign at the expansion audience

8. Managing Audiences​

View Audiences​

Go to Integrations → Meta Ads to see:

  • Active audience count
  • Total users targeted
  • Audience details (name, status, user count)

Delete Audiences​

Click the trash icon on any audience:

  • Deletes from both Flexsee and Meta Ads Manager
  • Cannot be undone
  • Confirmation modal prevents accidental deletion

Disconnect Integration​

Click "Disconnect" to:

  • Mark the Flexsee connection inactive
  • Stop syncing audiences
  • Existing audiences in Meta remain but won't update

9. Troubleshooting​

"Can't load URL: Domain isn't included in app's domains"​

Cause: The Flexsee Meta App’s domains or redirect URIs may need to be updated.

Fix: Contact support@flexsee.ai. You cannot change the Flexsee Meta App settings yourself.

"Business account needed to create/edit this audience"​

Cause: Using a personal ad account instead of Business account

Fix:

  1. Create a Business Manager account at business.facebook.com
  2. Create a Business ad account (not personal)
  3. Disconnect and reconnect Meta Ads in Flexsee
  4. OAuth will now use the Business account

"Custom Audience Terms not accepted"​

Cause: First-time Custom Audience creation requires accepting Meta's terms

Fix:

  1. Follow the link in the error message
  2. Review and accept Custom Audience Terms
  3. Retry creating the audience

"Permissions error" in Development mode​

Cause: Your Facebook account may not be a Tester on the Flexsee Meta App, or your ad account access may be limited.

Fix: Contact support@flexsee.ai to be added as a Tester. Ensure your ad account shows Owned by your Business in Business Settings → Ad accounts. Disconnect and reconnect Meta Ads in Flexsee.

"No ad accounts found"​

Cause: No ad accounts accessible, or none in Business Manager

Fix:

  1. Create a Business ad account in Business Manager
  2. Ensure you have Admin or Advertiser role
  3. Wait 5-10 minutes for Meta to sync
  4. Reconnect Meta Ads in Flexsee

"Update payment method" / "add a valid payment method"​

Cause: Your Meta ad account has no valid payment method. Meta requires one before you can run ads (including Publish advert).

Fix:

  1. Open Meta Business Settings → Billing and payment
  2. Add a payment method (card or other option) for the ad account you use with Flexsee
  3. Retry Publish advert

"Enter the person or organisation benefitting from the ads"​

Cause: Meta requires a Beneficiary for ads targeting the EU, UK, Australia and similar regions (DSA). Flexsee normally uses your ad account’s Business name automatically.

Fix: Ensure your ad account is Owned by your Business in Business Settings → Ad accounts. If it is and you still see this, in Meta go to Ad account → Advertising settings → Verifications & ad transparency → Beneficiary and payer and set a default. See the Beneficiary tip in section 1.

"Ads creative post was created by an app that is in development mode"​

Cause: Publish advert creates a live ad (campaign + ad set + creative + ad) via the API. Meta only allows that when the Flexsee Meta App is in Live mode. While the app is in Development, you can use Generate campaign with audience (Custom Audience only) and build the ad in Meta Ads Manager yourself; Publish advert will work after Flexsee's app has passed Meta App Review and is switched to Live.

Fix: No action on your side. Contact support@flexsee.ai if you need Publish advert before the app is Live; we can prioritize App Review.

"No Meta Pixel found for this ad account"​

Cause: You clicked Publish advert but your ad account has no Pixel connected. Conversion campaigns (optimized for purchases) require a Pixel so Meta knows which conversion source to use.

Fix: In Business Settings (business.facebook.com/settings) → Data sources → Datasets and pixels, create or add a dataset (Pixel) with + Add if the list is empty. Click the dataset in the list → Connected assets tab → Connect assets → Ad account → select the ad account you use in Flexsee. Retry Publish advert. Full steps: Meta Pixel (for Publish advert).

Audience or campaign creation fails (500 or generic error)​

Cause: Backend or Meta API issue.

Fix: Note the exact error message (or a screenshot) and contact support@flexsee.ai.

10. API Reference​

Create Audience Endpoint​

POST /meta-ads/audiences
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "name": "High-intent buyers for Product X",
  "productId": "product_id",
  "users": [
    {
      "user_id": "user123",
      "email": "user@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "phone": "+1234567890",
      "score": 0.85
    }
  ],
  "objective": "retargeting",
  "modelId": "model_id",
  "dailyBudget": 50
}

Response​

{
  "success": true,
  "audienceId": "uuid",
  "metaCustomAudienceId": "123456789",
  "userCount": 57,
  "status": "active",
  "message": "Meta Ads audience created successfully!"
}

List Audiences​

GET /meta-ads/audiences
Authorization: Bearer <jwt_token>

Returns all Meta audiences for your organization.

Connection Status​

GET /meta-ads/status
Authorization: Bearer <jwt_token>

Returns Meta connection status and ad account ID.

Support​

If you encounter issues:

For Meta-specific questions, consult Meta's Marketing API documentation.