Build the AI Marketing Agent (Facebook/Meta Ads)

1. What you're building

Every merchant on Kayroo already gets a free, in-house AI Marketing Expert that reads their abandoned checkouts, slow-moving inventory, and customer segments, and narrates advice about what to do. It never sends anything, posts anything, or spends anything — it's a report, not an actor.

This plugin is the opposite: an AI agent that actually does the marketing. It reads a store's real product catalog and recent orders through the Kayroo Connect API, uses an LLM with tool-use against the Meta Marketing API to draft Facebook/Meta ad campaigns, and — only once the merchant explicitly approves — publishes them to the merchant's own ad account, spending the merchant's own money.

• Reads the store's product catalog, recent orders, and delivery-fee context via the Kayroo public API.
• Drafts audience targeting, budget suggestions, ad creative (copy + which product images to use), and campaign structure (campaign → ad set → ad).
• Presents every draft to the merchant for explicit review and approval before anything goes live or any budget is committed.
• Once approved, publishes the campaign to the merchant's own Meta Business ad account, on the merchant's own ad billing.
• Feeds order/conversion data back to Meta via the Conversions API so campaign attribution improves over time.

What this first version explicitly does not do: write anything back into Kayroo, touch customer PII beyond what Meta's Conversions API itself requires (hashed, per Meta's own rules), or make any unsupervised spend decision.

2. Read the API guide before you start

This entire plugin is built on top of Kayroo Connect — Kayroo's public REST API and webhook system. This guide assumes you've already read that reference and understand tokens, scopes, endpoints, and webhook signature verification.

The trust model is identical to any other Kayroo integration: your service lives entirely on your own infrastructure and repository. You never get Kayroo source code, database credentials, server access, or an internal login — you only ever talk to a merchant's store through their API token and your registered webhook endpoint.

3. Step-by-step build plan

This is the recommended order to build Phase 1 in. Each step only depends on the ones before it.

1. Stand up your own hosted service (your infrastructure, your repository, your CI/CD) — this is where all of the following runs.
2. Build a merchant onboarding flow: a screen where the merchant pastes in a Kayroo API token (they mint it themselves from Admin → API Tokens, granting store.read + products.read + orders.read), and connects their own Meta Business account to your app via Meta's own OAuth flow.
3. Pull store context on connect: call GET /api/v1/store for currency/delivery fee, GET /api/v1/products for the catalog (images, prices, stock), and GET /api/v1/orders for recent order history — see the table in section 4 for exactly which fields matter here.
4. Register a webhook subscription (the merchant does this from Admin → Webhooks in their panel, pointing at your endpoint) for order.created and product.updated, so your campaign data and creative stay in sync without polling.
5. Use an LLM with tool-use against the Meta Marketing API to draft a campaign: audience targeting, budget suggestion, ad creative (copy + which product images from the catalog to use), and structure (campaign → ad set → ad).
6. Show the merchant every draft in a clear review screen and require explicit approval before anything is published or any budget is committed — see section 5, this step is mandatory, not optional.
7. On approval, publish the campaign to the merchant's own Meta Business ad account using Meta's API, billed entirely through the merchant's own Meta payment method.
8. When you receive an order.created webhook, send the matching conversion event to Meta's Conversions API (with customer PII hashed per Meta's own requirements) so ad performance and attribution improve over time.
9. When you receive a product.updated webhook, refresh the ad creative/catalog data you cached for that product so campaigns never advertise stale prices or out-of-stock items.

4. Data you pull from Kayroo Connect

Phase 1 only needs read scopes that already exist today. Request only these — don't ask a merchant for customers.read unless you're building Phase 2 (see section 8).

5. The human-in-the-loop rule (non-negotiable)

This is the single hardest requirement of this plugin, and it is not a style choice: your agent must never publish a campaign or commit a merchant's ad budget without that merchant explicitly approving it first, every time.

• Show a clear, readable draft (audience, budget, creative, structure) before anything is published — not a technical JSON dump.
• Require an explicit action (a real "Approve & publish" click) — never a default/timeout that auto-approves if the merchant doesn't respond.
• Any change to an already-approved and running campaign (budget increase, new creative, paused/resumed) needs the same explicit approval step, not just the initial launch.
• The agent may propose, explain, and recommend — but the merchant decides. Every time.

6. What you must never do

• Never hold, front, or move a merchant's ad spend yourself. Money only ever flows directly between the merchant and Meta — your plugin configures campaigns, it never touches payment.
• Never ask Kayroo or a merchant for direct database access, server access, SSH, or a copy of the Kayroo codebase. If something seems to require it, the fix is to ask Kayroo to extend the public API — not to get direct access.
• Never make an unsupervised spend or publish decision — see section 5.
• Never recompute logic Kayroo already exposes. For customer segmentation (Phase 2), read GET /api/v1/customers/segments instead of re-deriving RFM segments yourself from raw order data.
• Never share, aggregate, or resell one merchant's data — Kayroo-sourced or Meta-sourced — with or against another merchant.

7. Security & data handling requirements

• Store Kayroo API tokens and Meta OAuth tokens encrypted at rest in your own infrastructure — Kayroo never sees Meta tokens, and Meta never sees Kayroo tokens.
• Never log raw tokens, and never expose them in client-side code.
• Support prompt revocation: a merchant disabling your plugin or deleting their Kayroo API token must immediately cut off all access on your side too — treat it as a hard disconnect, not a transient error to retry.
• Hash or otherwise handle customer phone numbers and emails exactly per each channel's own requirements (Meta's Conversions API has its own hashing rules) — retain them only as long as that purpose needs, never for anything beyond this merchant's own marketing.
• Define and honor a retention window for any Kayroo-sourced data you cache (product/order data pulled via the API), and delete it on request or when a merchant disconnects.
• Log every action your agent takes (campaign drafted, merchant approved, campaign published, budget changed) on your own side, retrievable if a merchant disputes an action.
• Disclose any breach or suspected credential leak involving merchant data or ad-account access to Kayroo promptly.

8. Possible future phases — do not build yet

These are credible next steps once Phase 1 is live and proven — none of them are commissioned, and none of them should be built until Kayroo explicitly greenlights them. They're listed here so you understand where this integration could go, not as a spec to start on.

• Organic content agent — draft social captions and suggest which product photos to pair them with, for the merchant to post manually.
• Automated re-engagement outreach — WhatsApp/email sequences targeting the segments GET /api/v1/customers/segments already identifies (abandoned checkouts, at-risk customers, champions), with the same human-in-loop approval pattern as Phase 1. Don't reimplement the segmentation logic — read it from the API.
• SEO content assistance — meta title/description suggestions for storefront pages, read/written via the public API rather than duplicated from scratch.

9. How to get started

There's no central "become a Kayroo partner" registration flow yet — this is a direct, small-team collaboration, not a marketplace listing.

1. Email [email protected] to introduce your team and confirm you're building this specific opportunity (so two teams don't duplicate effort).
2. Read the Kayroo Connect developer guide at /developers end to end.
3. Get any Kayroo merchant on the Scale or Pay-as-you-go plan to mint you a test API token (Admin → API Tokens) with store.read, products.read, and orders.read — this can be a test store you set up yourself, since these plans are the ones where API access is available.
4. Build and test your onboarding, catalog sync, and draft-and-approve flow end to end against that test store before touching a live Meta ad account.

10. Questions?

If anything about the API, the webhook events, or the approval flow this plugin needs isn't covered by this guide or the developer guide at /developers, email [email protected] rather than guessing or working around it.