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)

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.ads.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',
    },
  },
});

result = client.ads.create_standalone_ad(
    account_id="acc_metaads_123",
    ad_account_id="act_1234567890",
    name="Spring sale - Purchase optimization",
    goal="conversions",
    budget_amount=75,
    budget_type="daily",
    headline="Spring Sale - 30% off",
    body="Limited time. Upgrade today.",
    image_url="https://cdn.example.com/spring.jpg",
    call_to_action="SHOP_NOW",
    link_url="https://example.com/spring",
    countries=["US"],
    promoted_object={
        "pixelId": "1729525464415281",
        "customEventType": "PURCHASE",
    },
)

curl -X POST "https://zernio.com/api/v1/ads/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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 below. zernio.ads.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"`).