Marketing

Two marketing surfaces live in the API:

• Meta integration (store.integrations.meta) — connect a Meta account per store, then read ad accounts, campaigns, ad sets, ads and KPIs, and maintain ad ↔ product links that join ad spend with the Feeef orders those products actually took.
• Pixel server events — server-side conversion events to Meta Pixel (Conversions API) and TikTok Pixel (Events API), fanned out to every pixel configured on the store.

Connect a Meta account

The OAuth handshake is store-scoped and authenticated end to end. Tokens are exchanged for a long-lived (~60 days) token, stored encrypted server-side, and never returned to clients — config reads expose only an oauth2Connected boolean (see the config envelope).

Meta integration — at a glance

All routes require a Bearer token plus store-member RBAC (reads: any member; writes: editor/admin/owner).

List queries share these params: adAccountId (required, act_ prefix optional), datePreset (e.g. last_7d) or since/until (YYYY-MM-DD; explicit range wins), effectiveStatus[] (ACTIVE, PAUSED, ARCHIVED, …), q (name search), after (Graph cursor), limit (1–100).

List campaigns with insights

curl -H "Authorization: Bearer $FEEEF_TOKEN" \
  "https://api.feeef.org/v1/stores/{storeId}/integrations/meta/ads/campaigns?adAccountId=act_1234567890&datePreset=last_7d&limit=25"

Ad ↔ product links

Feeef extracts each ad's destination URL, matches it to a store product (storefront hosts + extraStoreHosts from ads settings), and persists the mapping so ad KPIs can sit next to the product's real order counts. Resolution is lazy per page; POST …/ads/sync-links (body { "adAccountId": "act_…" }) forces a full sweep. Fix a wrong match with PATCH …/ads/links/{linkId} and body { "productId": "…" }.

Legacy pixel-connect routes

The pre-integration flow used for pixel discovery still exists and is public (raw access token passed by the client — prefer the store-scoped integration above for anything new):

Pixel server events

Server events need the pixel integrations, not the Meta account: configure store.integrations.metaPixel.pixels[] (each entry: pixel id + CAPI access token key) and store.integrations.tiktokPixel (pixel id + accessToken) via the integrations config API. Events are built from an order and fanned out to every configured pixel; the response reports per-pixel success.

Accepted event values:

Send a purchase event

curl -X POST "https://api.feeef.org/v1/actions/sendEventToMetaPixel" \
  -H "Authorization: Bearer $FEEEF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "event": "Purchase", "storeId": "{storeId}", "orderId": "{orderId}" }'

The fan-out response (HTTP 200 even on partial failure — inspect the counters):

{
  "event": "Purchase",
  "orderId": "…",
  "storeId": "…",
  "totalPixels": 2,
  "successfulPixels": 1,
  "failedPixels": 1,
  "successRate": 0.5,
  "hasAnySuccess": true,
  "results": [
    { "pixelId": "123", "pixelName": "Main", "success": true, "response": { "…": "…" } },
    { "pixelId": "456", "pixelName": "Backup", "success": false, "error": "…" }
  ],
  "summary": { "message": "Successfully sent event to 1 out of 2 pixels" }
}

Status rules

Pixel configs can carry status rules — "when the order transitions into status X, fire event Y". They run automatically on order updates; POST /v1/actions/runPixelStatusRules lets you audit or recover:

• Default is dry-run: reports which rules would fire for the order's transition without calling any pixel API.
• "dryRun": false actually sends.
• "force": true fires rules whose target equals the order's current status (recovery / verification after missed sends).

The response lists outcomes per rule with wouldFire, sent, and skipReason.

Requirements checklist

• Ads reads: store has a connected Meta account (capabilities.connected and canRead true) — tokens expire after ~60 days, watch needsReconnect.
• Meta server events: integrations.metaPixel.pixels[] entries with valid CAPI tokens.
• TikTok server events: integrations.tiktokPixel with a valid Events API token.
• Writes to marketing configs follow the same RBAC + store.integrations scope rules as every integration.

Related

• Integrations — config envelope, redaction, billing
• Connectors — Facebook Lead Ads → orders import
• API conventions — errors, pagination