Meta Conversion API

Use the Meta Conversion API integration to forward Superwall subscription lifecycle events to Meta over a server-side API. This is the integration to use when you want Meta to receive renewals, cancellations, expirations, refunds, and other webhook-driven revenue events.

Note: If you need browser-side tracking for web paywalls, see Facebook Pixel. That integration tracks client-side paywall events and does not send subscription lifecycle events.

Features

• Server-side event tracking: Events are sent directly to Meta's servers.
• Standard event mapping: Superwall maps subscription events to Meta standard events where possible.
• Sandbox environment support: Use separate credentials for sandbox events.
• Test event mode: Validate events in Meta Events Manager before going live.
• Flexible revenue reporting: Send gross revenue or net proceeds.
• Anonymous user handling: Control how events behave when a user has no originalAppUserId.
• Deduplication: Event IDs prevent duplicate event counting.

Set up in Superwall

Set this up from the dashboard UI, not by manually building a JSON payload.

1. Open your app in Superwall.
2. Go to Integrations.
3. In Marketing, open Meta Conversion API.
4. Fill in the fields shown in the form.
5. Click Enable Meta Conversion API.

If the integration is already connected, Superwall shows an overview with status, configured field count, recent delivery performance, and an Edit Configuration button.

Revenue tracking requirement

This integration depends on Superwall revenue tracking. If revenue tracking is not configured, the dashboard shows a Revenue tracking required banner and blocks the form until you set that up first.

Fields shown in the dashboard

Superwall handles the internal integration identifier automatically. You do not enter integration_id in the dashboard UI.

The current dashboard UI also does not expose custom event-name mappings for this integration, so setup is limited to the fields above.

Getting your credentials

Meta Events Manager is the source of truth for the credentials this integration needs.

Access token

1. Go to Meta Events Manager.
2. Select your Pixel from Data Sources.
3. Click the Settings tab.
4. Scroll to Conversions API.
5. Generate an access token, or use an existing System User token.
6. Copy the access token.

Note: The access token requires ads_management permission. For production use, Meta recommends using a System User token instead of a personal token.

Pixel ID

1. Go to Meta Events Manager.
2. Select your Pixel from Data Sources.
3. Copy the Pixel ID shown at the top of the page.

Test event code

1. In Events Manager, select your Pixel.
2. Click the Test Events tab.
3. Copy the displayed test event code.
4. Add it to the Test Event Code field while validating your integration.

Event mapping

Superwall maps revenue lifecycle events to Meta standard events when possible. Using standard events helps Meta optimize ad delivery for those outcomes.

Standard event mappings

Custom event mappings

Events without a standard Meta equivalent are sent with their Superwall event names by default:

Complete event mapping reference

Event format

Superwall sends events to Meta's Conversion API in the following format:

API endpoint

POST https://graph.facebook.com/v21.0/{pixel_id}/events?access_token={access_token}

Request payload

{
  "data": [
    {
      "event_name": "Subscribe",
      "event_time": 1705312200,
      "event_id": "evt_abc123",
      "action_source": "app",
      "user_data": {
        "external_id": ["user_12345"]
      },
      "custom_data": {
        "value": 9.99,
        "currency": "USD",
        "content_type": "product",
        "content_name": "com.app.premium.monthly",
        "content_ids": ["com.app.premium.monthly"]
      }
    }
  ],
  "test_event_code": "TEST12345"
}

Event fields

Custom data fields

User identification

Meta's server-side event matching depends on the external_id value that Superwall sends.

Known users

For users with an originalAppUserId, Superwall sends:

{
  "user_data": {
    "external_id": ["user_12345"]
  }
}

Anonymous users

For users without an originalAppUserId, behavior depends on the Anonymous User Behavior setting.

When set to "send":

• Events are sent with a synthetic ID using the store name and original transaction ID.

{
  "user_data": {
    "external_id": ["$APP_STORE:1000000123456789"]
  }
}

When set to "dontSend":

• Events from anonymous users are skipped.

Revenue tracking

The Sales Reporting setting controls which amount is sent in custom_data.

Revenue vs. proceeds

• Revenue: The full amount charged to the customer.
• Proceeds: The amount after store fees and taxes.

Zero-value events

Events without revenue, such as cancellations and expirations, omit value and currency:

{
  "custom_data": {
    "content_type": "product",
    "content_name": "com.app.premium.monthly",
    "content_ids": ["com.app.premium.monthly"]
  }
}

Refund events

Refunds are sent with a negative value:

{
  "event_name": "sw_refund",
  "custom_data": {
    "value": -9.99,
    "currency": "USD",
    "content_type": "product",
    "content_name": "com.app.premium.monthly",
    "content_ids": ["com.app.premium.monthly"]
  }
}

Sandbox handling

The integration supports separate credentials for sandbox events.

With sandbox credentials configured

When both Sandbox Pixel Id and Sandbox Access Token are provided:

• Production events use the main credentials.
• Sandbox events use the sandbox credentials.
• Events stay separated in Meta Events Manager.

Without sandbox credentials

When sandbox credentials are not provided:

• Production events are sent normally.
• Sandbox events are skipped entirely.
• Test data does not pollute your production Pixel.

Test event mode

Use the Test Event Code field to validate the integration without affecting production metrics.

1. Copy a test event code from Meta Events Manager.
2. Add it to the Test Event Code field.
3. Send test events from your app.
4. Verify the events in the Test Events tab.

Events sent with a test event code:

• Appear in Test Events
• Do not count toward main metrics
• Are not used for optimization

Remove the Test Event Code value before sending live traffic.

Testing the integration

Validate the integration end-to-end before relying on it for attribution.

1. Configure a test event code

Add a value to the Test Event Code field from Meta Events Manager.

2. Send test events

Trigger subscription events from your app in sandbox mode.

3. Verify in Meta Events Manager

1. Go to Meta Events Manager.
2. Select your Pixel.
3. Open Test Events.
4. Verify the event names, parameters, and user data.

4. Check event quality

1. Open your Pixel in Meta Events Manager.
2. Check the Event Match Quality score.
3. Review whether matching quality is acceptable for your use case.

5. Test scenarios

• Production event sends to the main Pixel
• Sandbox event sends to the sandbox Pixel when configured
• Sandbox event is skipped when sandbox credentials are not configured
• Trial start maps to StartTrial
• Subscription start maps to Subscribe
• Renewal maps to Purchase
• Cancellation sends as a custom event
• Anonymous users follow your configured behavior
• Revenue is included for paid events
• Test event code appears in Test Events

Best practices

1. Use System User tokens for production access.
2. Configure separate sandbox credentials for testing.
3. Remove the Test Event Code value before going live.
4. Keep external_id values consistent across data sources.
5. Monitor Event Match Quality in Events Manager.
6. Prefer Meta standard events when they fit your use case.

Common use cases

Optimizing campaigns for subscriptions

1. Send Subscribe events for new paid subscriptions.
2. Create a custom conversion in Meta Ads Manager based on Subscribe.
3. Optimize campaigns for subscription conversions.

Measuring trial-to-paid conversion

1. Track StartTrial for trial starts.
2. Track Purchase for trial conversions.
3. Build reporting in Meta around the conversion funnel.

Retargeting churned users

1. Track sw_subscription_cancelled.
2. Build a custom audience for cancelled users.
3. Run re-engagement campaigns with targeted offers.

Value-based optimization

1. Include revenue in custom_data.value.
2. Create value-based conversions in Meta.
3. Optimize for higher-value subscribers.

Troubleshooting

Events not appearing in Events Manager

Possible causes:

• Invalid access token
• Incorrect Pixel ID
• Sandbox events without sandbox credentials
• Test event code routing events into Test Events only

Solutions:

1. Verify your token has ads_management.
2. Confirm the Pixel ID matches Events Manager.
3. Check whether sandbox credentials are configured.
4. Clear the Test Event Code field if you expect the events in the main overview instead of Test Events.

Authentication errors (Error 190)

Possible causes:

• Expired token
• Missing permissions
• Revoked token

Solutions:

1. Generate a new access token.
2. Verify the token has ads_management.
3. Prefer a System User token for long-term stability.

Low event match quality

Possible causes:

• Only external_id is being sent
• Limited user data is available

Solutions:

• Keep external_id consistent with your other Meta data sources.
• Include additional user data if your webhook pipeline supports it.

Events show as duplicate

Possible causes:

• The same event is sent more than once
• Event ID collisions

Solutions:

• Superwall uses the event ID for deduplication.
• Verify that the same webhook is not being processed multiple times.

Wrong event names

Possible causes:

• The event type maps differently than expected

Solutions:

1. Compare the payload against the mapping table above.
2. Validate with the Test Event Code field.
3. If you need a different naming scheme, note that the current dashboard UI does not expose custom event-name mappings for this integration.

Rate limits

Meta's Conversion API has the following published limits:

The integration sends one event per webhook, which is well within those limits.

API reference

Endpoint

POST https://graph.facebook.com/v21.0/{pixel_id}/events

Authentication

The access token is passed as a URL parameter:

?access_token={access_token}

Request headers

Content-Type: application/json
Accept: */*

Response

Success (200 OK):

{
  "events_received": 1,
  "messages": [],
  "fbtrace_id": "ABC123..."
}

Error (400/401/403):

{
  "error": {
    "message": "Invalid OAuth access token.",
    "type": "OAuthException",
    "code": 190,
    "fbtrace_id": "ABC123..."
  }
}

Additional resources

• Meta Conversion API Documentation
• Server Events Parameters Reference
• Event Quality Scoring Guide
• App Events Best Practices
• Meta Events Manager
• Facebook Pixel for browser-side web paywall tracking