API reference
Meta Conversions API Reference
Destination management, public measurement capture and visitor suppression.
Connect eligible storefront events to Meta
An optional Meta Conversions API destination can forward supported PageView, ViewContent, AddToCart, InitiateCheckout and authoritative Purchase events. Configure the destination, event set and test code, verify the connection, then inspect redacted event outcomes.
Destination readiness, queued work, provider acceptance, Events Manager visibility and advertising attribution are different states. A configured worker or successful HTTP request alone does not prove an event reached Meta or produced a conversion.
Advertising measurement is separate from email enrollment
Meta forwarding uses its existing advertising-measurement permission and respects the supported Global Privacy Control, Do Not Track and visitor suppression checks. Purchasing or joining a developer email list does not supply that advertising permission. Declining measurement must not block ordinary browsing or checkout.
When enabled and permitted, events can include event/time/URL, product or order value, currency, browser matching identifiers and hashed customer matching fields. Hashing is not anonymization. Keep destination tokens private. A disconnect stops pending forwarding and removes saved destination credentials and supported checkout measurement snapshots; it does not erase history already held by Meta.
This integration does not change GA4 behavior or email preferences. Provider-side processing follows the developer destination and applicable provider terms. Use the existing privacy-request procedure for account-related requests; no new universal retention or delivery promise is made.
SoundSync
Measurement operations
GET
/api/developer/meta-capi
Read destination readiness and redacted delivery outcomes
- Auth
- Account Bearer JWT
- Scope
- settings.view and all-products scope for settings reads; settings.manage additionally required for saves, connection tests, replay and disconnect.
- Returns
- HTTP 200: destinationId, hasToken, mode, eventNames, testEventCode, verifiedAt, configured, encryptionReady, ready, workerEnabled, lastError, apiVersion, canManage, counts, lastSuccess, events.
Request, response and error reference
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"destinationId": {
"type": "string"
},
"hasToken": {
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"disabled",
"testing",
"live"
]
},
"eventNames": {
"type": "array",
"items": {
"type": "string"
}
},
"testEventCode": {
"type": "string"
},
"verifiedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"configured": {
"type": "boolean"
},
"encryptionReady": {
"type": "boolean"
},
"ready": {
"type": "boolean"
},
"workerEnabled": {
"type": "boolean"
},
"lastError": {
"type": "string"
},
"apiVersion": {
"type": "string"
},
"canManage": {
"type": "boolean"
},
"counts": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"lastSuccess": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"event_name": {
"type": "string"
},
"event_id": {
"type": "string"
},
"status": {
"type": "string"
},
"attempts": {
"type": "integer",
"minimum": 0
},
"replay_count": {
"type": "integer",
"minimum": 0
},
"explanation": {
"type": "string"
},
"canReplay": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500, 503.
PUT
/api/developer/meta-capi
Save an encrypted Meta destination and permitted event set
- Auth
- Account Bearer JWT
- Scope
- settings.view and all-products scope for settings reads; settings.manage additionally required for saves, connection tests, replay and disconnect.
- Request fields
- destinationId: string (required)
- accessToken: string
- mode: disabled | testing | live
- testEventCode: string
- eventNames: array (required)
- Returns
- HTTP 200: destinationId, hasToken, mode, eventNames, testEventCode, verifiedAt, configured, encryptionReady, ready, workerEnabled, lastError, apiVersion, canManage, counts, lastSuccess, events.
- Notes
- An access token is required on initial setup. Save new/replaced credentials disabled, save an Events Manager test code, run the synthetic test, then inspect accepted/verified state before activation. testing requires testEventCode. Changing configuration cancels queued work for the old generation; history is not rerouted.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"destinationId": {
"type": "string",
"pattern": "^[0-9]{5,30}$"
},
"accessToken": {
"type": "string",
"writeOnly": true
},
"mode": {
"type": "string",
"enum": [
"disabled",
"testing",
"live"
]
},
"testEventCode": {
"type": "string"
},
"eventNames": {
"type": "array",
"items": {
"type": "string",
"enum": [
"PageView",
"ViewContent",
"AddToCart",
"InitiateCheckout",
"Purchase"
]
}
}
},
"additionalProperties": true,
"required": [
"destinationId",
"eventNames"
]
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"destinationId": {
"type": "string"
},
"hasToken": {
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"disabled",
"testing",
"live"
]
},
"eventNames": {
"type": "array",
"items": {
"type": "string"
}
},
"testEventCode": {
"type": "string"
},
"verifiedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"configured": {
"type": "boolean"
},
"encryptionReady": {
"type": "boolean"
},
"ready": {
"type": "boolean"
},
"workerEnabled": {
"type": "boolean"
},
"lastError": {
"type": "string"
},
"apiVersion": {
"type": "string"
},
"canManage": {
"type": "boolean"
},
"counts": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"lastSuccess": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"event_name": {
"type": "string"
},
"event_id": {
"type": "string"
},
"status": {
"type": "string"
},
"attempts": {
"type": "integer",
"minimum": 0
},
"replay_count": {
"type": "integer",
"minimum": 0
},
"explanation": {
"type": "string"
},
"canReplay": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500, 503.
DELETE
/api/developer/meta-capi
Disconnect forwarding and remove saved destination credentials
- Auth
- Account Bearer JWT
- Scope
- settings.view and all-products scope for settings reads; settings.manage additionally required for saves, connection tests, replay and disconnect.
- Returns
- HTTP 200: destinationId, hasToken, mode, eventNames, testEventCode, verifiedAt, configured, encryptionReady, ready, workerEnabled, lastError, apiVersion, canManage, counts, lastSuccess, events.
- Notes
- Cancels pending events and removes saved checkout measurement snapshots. Provider-side history is separate. No browser Pixel is installed by this operation.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"destinationId": {
"type": "string"
},
"hasToken": {
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"disabled",
"testing",
"live"
]
},
"eventNames": {
"type": "array",
"items": {
"type": "string"
}
},
"testEventCode": {
"type": "string"
},
"verifiedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"configured": {
"type": "boolean"
},
"encryptionReady": {
"type": "boolean"
},
"ready": {
"type": "boolean"
},
"workerEnabled": {
"type": "boolean"
},
"lastError": {
"type": "string"
},
"apiVersion": {
"type": "string"
},
"canManage": {
"type": "boolean"
},
"counts": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"lastSuccess": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"event_name": {
"type": "string"
},
"event_id": {
"type": "string"
},
"status": {
"type": "string"
},
"attempts": {
"type": "integer",
"minimum": 0
},
"replay_count": {
"type": "integer",
"minimum": 0
},
"explanation": {
"type": "string"
},
"canReplay": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500, 503.
POST
/api/developer/meta-capi/test
Queue one explicitly synthetic connection test
- Auth
- Account Bearer JWT
- Scope
- settings.view and all-products scope for settings reads; settings.manage additionally required for saves, connection tests, replay and disconnect.
- Returns
- HTTP 200: destinationId, hasToken, mode, eventNames, testEventCode, verifiedAt, configured, encryptionReady, ready, workerEnabled, lastError, apiVersion, canManage, counts, lastSuccess, events.
- Notes
- Requires a saved destination/token and Events Manager test code. This queues an external test event; do not use as a harmless health read. HTTP success does not establish provider acceptance, Events Manager visibility or ad attribution. Inspect the returned event status after worker processing.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"destinationId": {
"type": "string"
},
"hasToken": {
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"disabled",
"testing",
"live"
]
},
"eventNames": {
"type": "array",
"items": {
"type": "string"
}
},
"testEventCode": {
"type": "string"
},
"verifiedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"configured": {
"type": "boolean"
},
"encryptionReady": {
"type": "boolean"
},
"ready": {
"type": "boolean"
},
"workerEnabled": {
"type": "boolean"
},
"lastError": {
"type": "string"
},
"apiVersion": {
"type": "string"
},
"canManage": {
"type": "boolean"
},
"counts": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"lastSuccess": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"event_name": {
"type": "string"
},
"event_id": {
"type": "string"
},
"status": {
"type": "string"
},
"attempts": {
"type": "integer",
"minimum": 0
},
"replay_count": {
"type": "integer",
"minimum": 0
},
"explanation": {
"type": "string"
},
"canReplay": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500, 503.
POST
/api/developer/meta-capi/events/{eventId}/replay
Requeue a recent eligible failed event for the same destination
- Auth
- Account Bearer JWT
- Scope
- settings.view and all-products scope for settings reads; settings.manage additionally required for saves, connection tests, replay and disconnect.
- Returns
- HTTP 200: destinationId, hasToken, mode, eventNames, testEventCode, verifiedAt, configured, encryptionReady, ready, workerEnabled, lastError, apiVersion, canManage, counts, lastSuccess, events.
- Notes
- Only failed events with retained payload, fewer than three replays, current destination/generation, recent original time and no suppression are eligible. Replay preserves event identity/time and cannot bypass expiry or recipient restrictions.
Request, response and error reference
No request body fields are read by this operation.
HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"destinationId": {
"type": "string"
},
"hasToken": {
"type": "boolean"
},
"mode": {
"type": "string",
"enum": [
"disabled",
"testing",
"live"
]
},
"eventNames": {
"type": "array",
"items": {
"type": "string"
}
},
"testEventCode": {
"type": "string"
},
"verifiedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"configured": {
"type": "boolean"
},
"encryptionReady": {
"type": "boolean"
},
"ready": {
"type": "boolean"
},
"workerEnabled": {
"type": "boolean"
},
"lastError": {
"type": "string"
},
"apiVersion": {
"type": "string"
},
"canManage": {
"type": "boolean"
},
"counts": {
"type": "object",
"properties": {},
"additionalProperties": true
},
"lastSuccess": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"event_name": {
"type": "string"
},
"event_id": {
"type": "string"
},
"status": {
"type": "string"
},
"attempts": {
"type": "integer",
"minimum": 0
},
"replay_count": {
"type": "integer",
"minimum": 0
},
"explanation": {
"type": "string"
},
"canReplay": {
"type": "boolean"
}
},
"additionalProperties": true
}
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500, 503.
POST
/api/meta-capi/config
Resolve whether measurement is available on this public surface
- Auth
- Public request; operation-specific verification still applies
- Scope
- Request Origin must match the validated published/verified public URL and developer surface.
- Request fields
- url: string (required)
- storefrontSlug: string
- productId: integer
- bundleId: integer
- Returns
- HTTP 200: available, developerId.
- Notes
- Scope/configuration failures return available:false. Availability is not visitor permission, provider acceptance or a guarantee that an event will be forwarded.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string"
},
"storefrontSlug": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"bundleId": {
"type": "integer",
"minimum": 1
}
},
"additionalProperties": true,
"required": [
"url"
]
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"available": {
"type": "boolean"
},
"developerId": {
"anyOf": [
{
"type": "integer",
"minimum": 1
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500, 503.
POST
/api/meta-capi/events
Submit eligible public measurement without blocking storefront use
- Auth
- Public request; operation-specific verification still applies
- Scope
- Validated developer surface, explicit advertising-measurement consent, matching destination, visitor ID and no GPC/DNT/suppression.
- Request fields
- url: string (required)
- storefrontSlug: string
- productId: integer
- bundleId: integer
- eventType: string (required)
- metadata: object
- adMeasurement: object (required)
- Returns
- HTTP 202: ok.
- Notes
- Maps supported page/product/cart activity to PageView/ViewContent/AddToCart. 202 ok:true deliberately does not disclose whether an event was retained or sent. Purchase capture is authoritative server checkout accounting, not a caller-supplied Purchase event. Email marketing enrollment is not advertising consent.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string"
},
"storefrontSlug": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"bundleId": {
"type": "integer",
"minimum": 1
},
"eventType": {
"type": "string"
},
"metadata": {
"type": "object",
"properties": {
"action": {
"type": "string"
}
},
"additionalProperties": true
},
"adMeasurement": {
"type": "object",
"properties": {
"developerId": {
"type": "integer",
"minimum": 1
},
"visitorId": {
"type": "string",
"format": "uuid"
},
"eventId": {
"type": "string",
"format": "uuid"
},
"consent": {
"type": "boolean"
},
"fbp": {
"type": "string"
},
"fbc": {
"type": "string"
},
"fbclid": {
"type": "string"
}
},
"additionalProperties": true
}
},
"additionalProperties": true,
"required": [
"url",
"eventType",
"adMeasurement"
]
}HTTP 202 response (application/json)
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500, 503.
POST
/api/meta-capi/privacy
Suppress the relevant visitor measurement and cancel pending work
- Auth
- Public request; operation-specific verification still applies
- Scope
- Validated public origin/developer surface and visitor identifier; cannot opt another developer into forwarding.
- Request fields
- url: string (required)
- storefrontSlug: string
- productId: integer
- bundleId: integer
- visitorId: string (required)
- Returns
- HTTP 200: ok.
- Notes
- Records the scoped measurement suppression when the surface resolves. Does not control GA4 or email lists. An unresolved surface can return ok:true without a suppression; a storage failure returns 503 and should be retried.
Request, response and error reference
Request (application/json)
{
"type": "object",
"properties": {
"url": {
"type": "string"
},
"storefrontSlug": {
"type": "string"
},
"productId": {
"type": "integer",
"minimum": 1
},
"bundleId": {
"type": "integer",
"minimum": 1
},
"visitorId": {
"type": "string",
"format": "uuid"
}
},
"additionalProperties": true,
"required": [
"url",
"visitorId"
]
}HTTP 200 response (application/json)
{
"type": "object",
"properties": {
"ok": {
"type": "boolean"
}
},
"additionalProperties": true
}Documented failures: 400, 401, 403, 404, 409, 500, 503.