List abandoned cart sessions: last activity, items, optional email captured before exit.

Use to estimate recovery potential or to feed a manual outreach campaign.

Trigger a recovery email to the captured address of an abandoned-cart session. The email contains a one-click recovery link with the cart pre-filled.

Idempotent: re-sending within the cooldown window is a no-op (wafle returns the existing send id).

List ads anomalies detected by the cron-driven detector (runs every 30 minutes). Each anomaly includes kind (cpa_spike, roas_break, conversion_drop, spend_overrun, learning_limited_stuck, tracking_drift), severity, scope, and the metrics that triggered it.

Anomalies fire admin-inbox notifications (warning+) and push notifications (critical only) with a 6h cooldown per (kind, scope_id) pair. Use this tool to read raw history.

Compute % overlap between custom audiences in the connected ad account. Returns a matrix (audience_a × audience_b → overlap_pct + overlap_users). Use this when the merchant runs many similar adsets — high overlap (>40%) typically means they're bidding against themselves and inflating CPM. Pass specific audience_ids to limit the matrix or omit to compare all audiences with > min_size users.

Note: Meta's overlap API is sampled (it builds the matrix once a day), so values may be a few hours stale. The wafle backend caches results for 6 hours per (slug, audience_set) tuple.

Per-creative performance breakdown for a campaign (or whole account if campaign_id omitted). Returns spend, impressions, clicks, conversions, ROAS and CPA for every creative_id active in the window. Cross-tabbed against wafle CAPI orders, so ROAS reflects server-side truth, not Meta's pixel.

Use when you need to find the one creative carrying a campaign vs the ones bleeding spend. Sort defaults to spend desc; a winner flag tags creatives whose ROAS is in the top quartile AND spend is above the per-creative significance floor (default 5,000 cents).

Pause many Meta campaigns in a single tool call. Returns per-id success/failure so partial successes are visible.

Best for ROAS-floor sweeps ("pause everything below 1.5x last 7d") and seasonal cleanup. The wafle backend serializes the underlying Marketing API requests with a 1 RPS throttle to stay below Meta's per-app rate limit.

Pause a Meta Ads campaign by id. Idempotent — pausing an already-paused campaign returns ok=true. Uses the tenant's connected Meta access token; the LLM does not need to pass credentials.

Use when ROAS is below threshold or as the apply step of a pause-recommendation. For multi-campaign pauses, prefer wafle_ads_bulk_pause to avoid round-trip cost.

Resume a paused Meta Ads campaign by id. Sets status to ACTIVE. Idempotent for already-active campaigns.

Note: campaigns paused for 14+ days lose their Learning Phase signal — Meta will re-enter Learning when you resume them.

Update a Meta campaign's budget. Pass daily_budget_cents (preferred) or lifetime_budget_cents — the two are mutually exclusive in the Marketing API.

Cents are in the ad account currency. The recommender follows a +30% / max +50% rule when scaling winners; if you call this directly, mirror that constraint to avoid blowing the Learning Phase.

Compare two date ranges (e.g. '2026-04' vs '2026-03', or two arbitrary date windows) and return delta % per metric: spend, revenue, ROAS, CPA, conversions, profit. Both ranges are evaluated against the wafle CAPI server-side truth so the comparison is honest (Meta's pixel attribution can drift quarter to quarter and produce false deltas).

Use to answer 'how did April do vs March?' or 'did the new creative pack improve things in the last 14 days vs the prior 14?'. Ranges can be passed as ISO months or as start/end dates; the two windows must NOT overlap.

Daily timeseries for a single creative_id since since. Each row: spend, impressions, clicks, conversions, revenue, roas, frequency, ctr, cpm.

Use to detect (a) Learning Phase exit, (b) creative fatigue (frequency rising + CTR falling), (c) the right scale moment (3+ days of stable ROAS above target). The response also includes fatigue_score (0..1, higher = more fatigued) and phase ∈ {learning, active, fatigued, off}.

Generate a structured monthly ads report for a store. Returns total spend, total revenue, profit, blended ROAS, top 5 winning campaigns, bottom 5 losing campaigns, and a recommendations array of human-readable strings. Designed as the input for Claude to author the executive narrative — DO NOT paste raw JSON into the report; rewrite into prose using recommendations as bullet points and the winners/losers as supporting evidence.

Backed by /stores/:slug/marketing/profit?range=... (which already aggregates spend × wafle revenue per campaign) plus a month-aware aggregation layer.

Account-level cross-tabbed performance — joins Meta Marketing API spend/impressions/clicks with wafle CAPI orders/revenue.

Each campaign returns: spend, meta_reported_orders (from pixel), wafle_orders (server-side truth), cpa_real_cents (spend / wafle_orders), roas_real, learning_phase, plus a prev_period block for trend analysis. Use this as the input to any optimization decision — it's what the recommender feeds the LLM.

READ-ONLY proposer: returns a list of adsets with ROAS below threshold_roas AND spend above min_spend_cents over range. Each item carries a recommendation ∈ {pause, reduce_budget, keep} based on (a) how far below threshold, (b) Learning Phase status, (c) trend vs previous period.

This tool NEVER mutates. To execute, the caller must explicitly call wafle_ads_campaign_pause, wafle_ads_bulk_pause, or wafle_ads_campaign_update_budget with the ids returned here. The output is shaped to be pasted back into a follow-up tool call by the LLM.

Apply a wafle ads recommendation by id — runs the underlying writer action (pause campaign, raise budget, etc.) and marks the recommendation applied. Idempotent: re-applying returns the previous result.

If the action requires human judgment (request_human_review, generate_creative_variants), the call queues the work and returns ok=true with queued: true.

List ads recommendations generated by wafle's AI engine. Recommendations cross-tab the Meta API spend with the server-side truth (wafle CAPI orders + revenue), so CPA/ROAS reflect what actually happened — not Meta's own attribution.

Each card has: title, description, action (the actual writer call to apply it), confidence (0..1), expected_impact, severity. Apply with wafle_ads_recommendation_apply.

Run a full ads-platform catalog sync (Meta Catalog API or equivalent) AND wait until it finishes. Emits progress notifications.

Long-running (5+ minutes for large catalogs). For fire-and-forget, call the underlying create endpoint directly.

Activate an agent — moves status to active, which makes it eligible for scheduled/event triggers. No-op if already active.

Create a new custom agent. Two paths:

1. from_template — clone one of the 5 pre-armed templates (customer-support-bot, content-writer-nightly, stock-watcher, abandoned-recovery, fraud-detector). Override slug/name if needed.

2. From scratch — supply name, system_prompt, tools_allowed, guardrails, trigger_type (+ trigger_config). Use wafle_agents_tool_catalog first to see what tools exist.

Cost guardrail (max_cost_per_run_cents) is hard-capped at 5000 (USD 50). Max turns is hard-capped at 50.

Get one agent by its slug — full definition including system_prompt, tools_allowed, guardrails, trigger_config and stats counters.

List custom agents defined for a store. Each agent has system_prompt + tools whitelist + guardrails + trigger. Filter by status (draft/active/paused/archived) or trigger_type.

Pause an active agent. Triggers stop firing; existing runs unaffected.

Manually dispatch a run for an agent. Returns the run_id and the synchronous run row (ends in status=done|failed|awaiting_approval). Use wafle_agents_runs_get to poll.

Approve a run that is awaiting_approval. Resumes execution from the pending tool call. Optional note saved to the audit log.

Get a specific run with its full conversation + audit log (steps: user_input, assistant_text, tool_call, tool_result, approval_request, approval_granted, error).

List runs for an agent — paginated, filterable by status. Each row: status, tokens, cost_cents, duration_ms.

Reject a run that is awaiting_approval. Run goes to cancelled; the pending tool call is NOT executed.

Aggregated stats for an agent: total runs, success rate, total cost, top tool names called.

List the 5 pre-armed agent templates: customer-support-bot, content-writer-nightly, stock-watcher, abandoned-recovery, fraud-detector. Use the id field as from_template in wafle_agents_create.

List the catalog of tools that can be added to an agent's tools_allowed. Each entry: name, description, scope required, destructive flag, JSON Schema for input.

Patch an existing agent — change system_prompt, tools_allowed, guardrails, trigger_config, model, status, etc. Slug + tenant_id are immutable.

Auto-classify products without a category. Call with a list of SKUs and a list of allowed categories. Each product gets { category, confidence } (or null if nothing fits). Accept the job to write category overrides into the catalog.

Apply an AI job's output to the platform.

• product_description → writes data.descriptions. on the catalog row.

• categorize → writes data.category overrides on each product row.

• review_summary → caches summary on the reviews aggregates row. Other types have no platform side effect (translation already cached, segment_compile is read-only).

Save user edits on an AI job's output and apply them. For product_description, the edited text is what gets written to data.descriptions..

Fetch a single AI job by id. Includes input_payload, output_payload, tokens, cost, model, duration, and user review status.

Paginated list of AI jobs for a store. Filter by job_type, status, or user_review. Use to surface a 'pending review' queue or to find a specific recent job.

Mark an AI job's output as rejected. Use to keep usage stats clean and to preserve learning signal for prompt tuning.

Generate a sales copy description for a product. Reads name + attributes + images from the catalog, runs the configured LLM, and stores the output as a 'pending review' job. Call wafle_ai_jobs_accept to apply it (writes data.descriptions. on the catalog row).

Tone: 'persuasivo' | 'tecnico' | 'breve'. Length is approximate words (±15%).

Summarize the approved reviews of a product into 2–3 sentences plus sentiment + key points. Output goes into a job; call wafle_ai_jobs_accept to cache the summary on the reviews aggregate row (24h TTL).

Compile a natural-language description (e.g. 'clientes que compraron al menos 2 veces y abandonaron carro últimos 30 días') into the email-marketing segmentation DSL. Returns { dsl_json, validated, errors }. Pass dsl_json straight into a new segment.

Customer-service co-pilot: classify an inbound message, gauge sentiment, decide if it needs escalation, and draft a friendly response. PII (emails, phones) in the message is redacted before being sent to the LLM.

Translate a piece of text from one language to another. Cached by sha256(source_text|source_lang|target_lang) — re-translating the same input is free.

Preserves markdown, lists, links and {{placeholders}}. Use for product descriptions, emails, or short copy snippets. Source and target are language codes ('es', 'en', 'pt', 'es-AR', 'pt-BR').

Token + cost aggregate for a store since a date (defaults to last 30 days). Use for the AI dashboard chart and quota guidance.

Time-series breakdown of analytics: revenue + orders bucketed by day/week/month.

Use for charts and 'compare last 30d to previous 30d' workflows.

High-level KPIs for a store over a window: orders, revenue, AOV, top products, conversion funnel, abandoned-cart rate.

Use as the starting point of any 'how is store X doing?' question.

Create a new wafle API key with the given scopes. Returns the secret ONCE — store it immediately.

Use when onboarding a new dashboard user, integration, or agent. Prefer narrowly-scoped keys.

If the wafle backend has not yet implemented /auth/keys POST, this tool returns the upstream error untouched.

Admin-only: tenant clients cannot mint API keys.

List API keys associated with the master account (or with a specific store, if the upstream key supports it).

Returns prefix + scopes for each key. Full secrets are NEVER returned by wafle. Use to audit who has access.

Admin-only: tenant clients cannot enumerate API keys.

Return information about the wafle admin key currently configured for this MCP server.

Use this to verify the server is correctly authenticated before running other tools, or to debug a 401 error. The response is { ok: true, type: 'master' | 'store', store_slug?, scopes? }.

Do NOT use this to authenticate end-user requests — wafle's REST has separate magic-link auth for storefront customers.

List abandoned carts (cart_token has items but no paid order in wafle_orders) for a customer email hash. Used by retargeting drip flows to surface 'you left X in your cart' nudges.

Fetch one order from wafle_orders. order_id accepts either the numeric primary key or the public id (WK-YYYY-NNN-rand) shown on the order detail page.

Manually flip a transfer/cash order to paid (proof-of-deposit verified, cash collected at delivery). Returns 422 if the order is on a webhook-driven gateway (mp / stripe) — those move via /webhooks/* automatically.

Refund a paid order — full when amount_cents is omitted/0, partial otherwise. Guardrail: any refund > 50% of total_cents requires confirm:true. The refund is recorded on the wafle_orders row; the gateway-side refund call is gateway-specific and currently records manual_refund:true in metadata (gateway API integration ships in v2).

Resend a transactional email tied to an order. Default template: order_confirmation. Idempotency-keyed by template+public_id+timestamp so retries don't double-send within the same minute.

List orders from the wafle_orders table for a store. Returns the new checkout pipeline (cart→MP/Stripe/transfer→paid). Filterable by status, date floor (since, ISO 8601), and customer email. For legacy WC orders use wafle_orders_list (different table).

Create a coupon. Codes are case-insensitive. Date fields are epoch seconds (0 = no bound).

Common patterns:

• type=percentage, value=10 → 10% off whole cart.

• type=fixed, value=5000, applies_to='product', applies_to_ids=[123] → ARS 5000 off product 123.

• type=free_shipping → no shipping cost.

Delete a coupon by id. Past usage history is preserved on orders.

List all coupons of a store. Each row: code, type, value, usage, validity dates, applies-to scope.

Use to audit active discounts or to find a code before editing.

Patch a coupon by id. Only sent fields change.

Import a CSV product feed into a store with catalog_mode=csv. Long-running. Emits progress notifications during the import (rows processed / total).

Returns the final import summary: imported, updated, errors, duration.

Fetch a single customer profile by email. Returns aggregated stats: lifetime value, order count, last seen, top SKUs.

List customers of a store with pagination + filters: search by email/name, has-orders, segment.

Wafle treats customers as derived data over orders — there's no separate sign-up table for storefronts.

List the orders of a single customer (by email).

List all customer segments configured for a store. Segments power the segment= filter in wafle_customers_list and the audience exports.

Attach a new custom domain (e.g. 'mi-tienda.com') to a wafle store. Wafle generates a verification_token and returns the 3 alternative DNS instructions the tenant must apply.

After creating, the tenant updates DNS at their provider, then call wafle_domains_verify (or wait for the 5min cron) to drive verification + SSL + nginx provisioning.

Validation rules: lowercase FQDN only, no IPs, no wildcards, no .wafle.click subdomains, max 10 active domains per tenant.

List the custom domains attached to a wafle store. Returns each domain's status (pending_verification / verifying / ssl_pending / active / ssl_failed / disabled), SSL expiry, verification token, and DNS-setup instructions for all 3 verification methods (TXT/CNAME/file).

Use first when the user asks 'what domains does store X have?' or before giving DNS instructions to a new tenant.

Fetch the full status of a single attached domain — current status (pending/verifying/active/etc), SSL expiry, last renewal, log of recent events. Includes the original DNS-setup instructions so you can re-show them to the tenant.

Use to answer 'is mi-tienda.com working yet?' or to debug a stuck verification.

Trigger immediate verification + SSL + nginx provisioning for a previously-added domain. Idempotent — safe to call repeatedly. The pipeline:

1. Probe TXT / CNAME / file methods (any one passes).

2. If passed → request a Let's Encrypt cert via acme.sh.

3. Render the per-domain nginx config and signal a reload.

4. Mark the domain active and append events to the log.

Rate-limited to 1 attempt per minute per domain (DNS + acme upstream).

Export the customer list of a store as CSV (default) or JSON. Includes email, name, phone, total spent, order count, last seen.

Use for CRM imports or general data exports. Wafle returns the raw CSV/JSON in the response body — for large stores prefer the dashboard download flow.

Export an audience formatted for Google Ads Customer Match: hashed email/phone with the column names Google expects.

Export an audience formatted for Meta (Facebook/Instagram) custom audiences: hashed email + phone per row, schema-compatible with Meta's CSV upload.

Filter by segment to build retargeting (high-intent, recovered, top-spenders) cohorts.

Create a new gateway. Types:

• mp_ar | mp_mx | mp_co | mp_cl: MercadoPago, requires creds.access_token + creds.public_key.

• stripe: requires creds.secret_key + creds.publishable_key.

• transfer: requires meta.cbu, meta.cbu_alias, meta.cbu_titular, meta.cbu_cuit.

After creating, run wafle_gateways_test to verify credentials before pointing a store at it.

Delete a gateway. Fails if the gateway is currently the default for any store — switch the store first.

Destructive and irreversible. Confirm with the user.

List all payment gateways across all stores (master view). Each gateway includes type, currency, active flag, store association.

Use to audit which stores have which gateways configured. Secrets are NEVER returned (only {set:true} markers).

Run a live credential test against the gateway provider. For MP it calls users/me; for Stripe it calls accounts/account; for transfer it returns ok.

Use after wafle_gateways_create or wafle_gateways_update (rotated creds). Read-only on the upstream provider.

Patch an existing gateway. Use to rotate credentials (creds) or toggle active.

Destructive in the sense that an inactive gateway will reject new charges; live transactions in flight are unaffected.

Invite a teammate to a tenant by email. Sends an invitation email with a magic link.

Requires the actor to be owner or admin of the target tenant.

List all members of a tenant — accepted memberships + pending invitations. Requires owner or admin role.

Update a member's role / scopes / is_active for a given tenant. Requires owner role on the tenant.

Add an internal or customer-visible note to an order. Notes appear in the timeline and (if customer=true) in the customer's order detail page + email.

Cancel an order. If the gateway supports auto-refund and the order was paid, wafle will trigger the refund.

Destructive: the order moves to cancelled and inventory is restocked. Confirm with the user before running.

Manually create an order. Use only for migrations or telephone sales — normal orders flow from the storefront.

Body uses canonical snake_case shape: items[]+payment_method+gateway_id (see waffle-docs/API-CONVENTIONS.md). Idempotency-Key header is auto-set; safe to retry on transient errors.

Fetch a single order by id. Returns customer, items, totals, gateway info, status, shipment data, timeline reference.

List orders for a store with pagination + filters. Filters: status, date range, customer email, search.

Use this for any 'pendientes', 'enviados', 'últimos N días' style query. The response includes meta.gatewayId and meta.gatewayType so you can correlate with payment status.

Refund a paid order, fully or partially. The refund is sent through whichever gateway captured the payment (MercadoPago / Stripe / manual transfer).

Destructive AND irreversible. Confirm amount before calling.

Mark an order as shipped. Records the carrier, tracking number, and updates status to shipped.

Triggers the customer notification email if the store has it enabled.

Get the chronological timeline of an order: status changes, payment events, shipment, notes, refunds.

Use to audit how an order got into its current state.

Fetch the current marketing pixel IDs configured for a store: Meta (Facebook), TikTok, GA4, Google Ads.

Set / update marketing pixel IDs of a store. Pass only the pixels you want to change; omit fields stay untouched. Pass null to clear a pixel.

Compute the final price of a list of (sku, qty) pairs given the store's current rules. Returns base price, applied rules, final price.

Use as a sanity check before publishing pricing changes — answers 'how much would I be charging?' without disturbing the live cart.

Create a new pricing rule. Types:

• multiplier: catalog-wide markup (e.g. 2.2 = +120% on every base price).

• discount_tier: percentage discount when subtotal crosses a threshold.

• category_markup: per-category multiplier override.

• fixed_price: pin a specific SKU to a fixed price (overrides multiplier).

Always preview with wafle_pricing_compute_preview before committing rules in production.

Delete a pricing rule by id. Irreversible — confirm before calling.

List all dynamic pricing rules of a store: catalog-wide multipliers, category markups, sale discount tiers, fixed prices on specific SKUs.

Use before editing — pricing rules compose, so you need to know what's already there.

Patch an existing pricing rule by id.

Manually create a product in a store whose catalog_mode = manual.

Do NOT use on stores with catalog_mode = supabase_sync — those products come from the upstream catalog and a manual create will be overwritten on next sync. For sync stores, use wafle_products_override to tweak fields without losing them on sync.

Fetch a single product by slug (the URL-friendly id). Returns full detail including variants, images, attributes and overrides.

List products of a single store with pagination + optional search/filter. Returns id, slug, name, sku, price, stock, status, images.

Use to browse catalog or to find a product id before editing/overriding.

Set per-product overrides (price, name, description, images) that survive catalog syncs. Use on supabase_sync stores when you need to tweak a single product without forking the whole catalog.

Wafle stores overrides server-side and re-applies them after every sync.

Lightweight search of products by name/sku. Equivalent to wafle_products_list with search set, but optimized for autocomplete.

Get the status of a product-sync job (pending|running|done|failed). Pair with wafle_products_sync_trigger.

Trigger an asynchronous catalog sync for a store. Returns a job id; poll wafle_products_sync_status until done.

Only meaningful on catalog_mode = supabase_sync stores. On manual stores it's a no-op error.