Conversion campaigns and promoted objects

Optimization goals that point at a specific event/page/app need a promotedObject on the ad set. Without it Meta rejects the ad-set create with error_subcode: 1815430 ("Please select a promoted object for your ad set."). Zernio enforces this upfront so you get a clean 400 invalid_request_error with param: "promotedObject" instead of a passthrough Meta error.

`goal`	Meta objective + optimization	Required `promotedObject` fields
`conversions`	Sales → `OFFSITE_CONVERSIONS`	`pixelId` + `customEventType` (a commerce event, e.g. `PURCHASE`, `ADD_TO_CART`, `START_TRIAL`)
`lead_conversion`	Leads → `OFFSITE_CONVERSIONS`	`pixelId` + `customEventType` (a leads event, e.g. `LEAD`, `SUBMIT_APPLICATION`, `SCHEDULE`, `CONTACT`)
`app_promotion`	App promotion → `APP_INSTALLS`	`applicationId` + `objectStoreUrl`
`lead_generation`	Leads → `LEAD_GENERATION` (instant form)	`pageId` (auto-filled from the connected Page when omitted)
`catalog_sales`	Sales → catalog template creative	`productSetId` + `pixelId` + `customEventType` — see Catalog Ads

customEventType accepts Meta's standard event names: PURCHASE, LEAD, COMPLETE_REGISTRATION, ADD_TO_CART, INITIATE_CHECKOUT, ADD_PAYMENT_INFO, SUBSCRIBE, START_TRIAL, VIEW_CONTENT, SEARCH, CONTACT, SUBMIT_APPLICATION, SCHEDULE. Custom-conversion-driven optimization is supported via customConversionId instead of (or alongside) customEventType.

conversions vs lead_conversion. Meta gates which conversion events are valid by campaign objective. conversions runs the Sales objective (commerce events like PURCHASE); a leads event such as LEAD is rejected there. For website pixel lead optimization use lead_conversion (the Leads objective with OFFSITE_CONVERSIONS). lead_generation is also the Leads objective but optimizes for an instant form (leadGenFormId) rather than a website pixel event.

Override the ad-set optimization goal. By default the ad-set optimization_goal is derived from goal (e.g. traffic → LINK_CLICKS). Pass optimizationGoal to set it explicitly, e.g. "LANDING_PAGE_VIEWS", "REACH", "IMPRESSIONS", "OFFSITE_CONVERSIONS", "THRUPLAY". It's forwarded verbatim and Meta validates it against the campaign objective (incompatible combinations are rejected).

const result = await zernio.adcampaigns.createStandaloneAd({
  body: {
    accountId: 'acc_metaads_123',
    adAccountId: 'act_1234567890',
    name: 'Spring sale - Purchase optimization',
    goal: 'conversions',
    budgetAmount: 75,
    budgetType: 'daily',
    headline: 'Spring Sale - 30% off',
    body: 'Limited time. Upgrade today.',
    imageUrl: 'https://cdn.example.com/spring.jpg',
    callToAction: 'SHOP_NOW',
    linkUrl: 'https://example.com/spring',
    countries: ['US'],
    promotedObject: {
      pixelId: '1729525464415281',
      customEventType: 'PURCHASE',
    },
  },
});

Need a pixel ID? Use zernio.trackingtags.listTrackingTags() to list the pixels a connected ad account can see (or zernio.trackingtags.createTrackingTag() to make one) — see Meta Pixels. zernio.conversions.listConversionDestinations() returns the same set, in case you're already wiring that.

Other Meta-specific knobs on promotedObject:

Field	When you'd use it
`customConversionId`	Optimising against a Custom Conversion (instead of a standard event). Pair with `pixelId`.
`productCatalogId` + `productSetId`	Catalog Ads / Advantage+ Shopping campaigns.
`applicationId` + `objectStoreUrl`	App-install / app-engagement campaigns (`goal: "app_promotion"`).
`offlineConversionDataSetId`	Optimise toward an offline event set. Post-merger these are datasets: the id is the dataset id (for pixel-backed datasets, the pixel id). Meta validates it's a real dataset.
`whatsappPhoneNumber`	The WhatsApp number on messaging-destination ad sets.

promotedObject is strict. The accepted keys are exactly: pixelId, customEventType, customEventStr, pageId, applicationId, objectStoreUrl, customConversionId, productCatalogId, productSetId, offlineConversionDataSetId, whatsappPhoneNumber. An unknown or typo'd key returns a 400 instead of being silently dropped. A silently dropped key used to change what the ad set optimized toward without warning.

The same object (same keys, same strictness) is editable after launch via platformSpecificData.promotedObject on PUT /v1/ads/ad-sets/{adSetId}.